Skip to main content
The chatcli connect command transforms your local terminal into a client that connects to a remote ChatCLI server. The entire interactive experience (sessions, contexts, agent, coder) works transparently, as if the LLM were running locally.

​
Basic Connection

1

Connect to the server

# Connect using positional address
chatcli connect myserver:50051

# Connect with explicit flag
chatcli connect --addr myserver:50051
2

Verify server information

Upon connecting, ChatCLI displays server information:
Connected to ChatCLI server (version: 1.2.0, provider: CLAUDEAI, model: claude-sonnet-4-5)
If the server has an active K8s Watcher, it also shows:
K8s watcher active: deployment/myapp in namespace/production (context injected into all prompts)

​
All Flags

FlagDescriptionEnv Var
--addr <host:port>Server addressCHATCLI_REMOTE_ADDR
--token <string>Authentication tokenCHATCLI_REMOTE_TOKEN
--provider <name>Overrides the server’s LLM provider
--model <name>Overrides the server’s LLM model
--llm-key <string>Your own API key (sent to the server)CHATCLI_CLIENT_API_KEY
--use-local-authUses OAuth credentials from the local auth store
--tlsEnables TLS connection
--ca-cert <path>CA certificate for TLS verification
-p <prompt>One-shot mode: send prompt and exit
--rawRaw output (no Markdown/ANSI formatting)
--max-tokens <int>Maximum tokens in response

​
StackSpot Flags

FlagDescription
--client-idStackSpot Client ID
--client-keyStackSpot Client Key
--realmStackSpot Realm/Tenant
--agent-idStackSpot Agent ID

​
Ollama Flags

FlagDescription
--ollama-urlOllama base URL (e.g., http://gpu:11434)

​
Credential Modes

You can choose how to authenticate with the LLM provider:
Do not send any credential flags. The server uses its own API keys:
chatcli connect myserver:50051

​
One-Shot Mode via Connect

Send a single prompt to the remote server and receive the response: 
# Simple prompt
chatcli connect myserver:50051 -p "Explain K8s pods"

# With your credentials
chatcli connect myserver:50051 --use-local-auth -p "Summarize the cluster status"

# Raw output (no markdown) for use in scripts
chatcli connect myserver:50051 -p "List pods with issues" --raw

​
Interactive Mode

Without the -p flag, ChatCLI starts the full interactive mode: 
chatcli connect myserver:50051
You have access to all ChatCLI features:
  • Sessions: /session save, /session load, /session list
  • Agent: /agent <task> or /run <task>
  • Coder: /coder <task>
  • Context: @file, @git, @command, @env, @history
  • Persistence: /context create, /context attach
  • Switch: /switch to change provider/model
  • Watcher: /watch status to see K8s Watcher status

​
Remote Resource Discovery

Upon connecting, the client automatically discovers plugins, agents, and skills available on the server: 
Connected to ChatCLI server (version: 1.3.0, provider: CLAUDEAI, model: claude-sonnet-4-5)
 Server has 3 plugins, 2 agents, 4 skills available
Server plugins appear in /plugin list with the [remote] tag. They are executed on the server — the client sends the command via gRPC and receives the result:
# List plugins (local + remote)
/plugin list

Installed Plugins (2):
  * @hello          - Example plugin                        [local]
  * @k8s-diagnose   - K8s cluster diagnostics               [remote]

​
Hybrid Mode

  • Local and remote plugins coexist; the [remote] prefix indicates the origin
  • Local and remote agents are listed together; when loading, resolution is transparent
  • When disconnecting (/disconnect), remote resources are automatically removed

​
Check K8s Watcher Status

If the server has an active K8s Watcher, you can query the status remotely: 
# In interactive mode
/watch status
Example output: 
K8s Watcher Status (Remote Server)
  Deployment:  myapp
  Namespace:   production
  Snapshots:   42
  Alerts:      2
  Pods:        3

Status Summary:
  3/3 pods running, 2 restarts last 1h
  Recent Events: Readiness probe succeeded on all pods

​
Environment Variables

Configure default values via environment variables to avoid typing flags every time: 
# In your .bashrc or .zshrc
export CHATCLI_REMOTE_ADDR=myserver:50051
export CHATCLI_REMOTE_TOKEN=my-token

# Now just:
chatcli connect

​
TLS and Security

1

Insecure Connection (Development)

chatcli connect localhost:50051
When TLS is disabled, a warning is logged by the client as a reminder that the connection is not encrypted. In production, enable TLS.
2

Connection with TLS

chatcli connect myserver:50051 --tls

# With custom CA certificate
chatcli connect myserver:50051 --tls --ca-cert /path/to/ca.pem
3

Token + TLS (Production)

chatcli connect myserver:50051 --tls --token my-secret-token
For a complete security guide (authentication, container hardening, RBAC, etc.), see the security documentation.

​
Load Balancing with Multiple Replicas

When the ChatCLI server runs with multiple replicas in Kubernetes, the client automatically distributes connections across available pods:
  • The client uses client-side round-robin via gRPC dns:/// resolver
  • Requires a headless Service (ClusterIP: None) in Kubernetes
  • Built-in keepalive (ping every 10s) detects inactive pods and reconnects quickly
  • In the Helm chart, enable service.headless: true when replicaCount > 1
  • In the Operator, headless is activated automatically when spec.replicas > 1

​
Practical Examples

# Local development: server without auth
chatcli connect localhost:50051

# Production: TLS + auth + your credentials
chatcli connect prod-server:50051 --tls --token secret --use-local-auth

# CI/CD: one-shot with specific provider
chatcli connect ci-server:50051 --provider GOOGLEAI --llm-key AIzaSy-xxx \
  -p "Analyze this diff: $(git diff HEAD~1)" --raw

# GPU server with Ollama
chatcli connect gpu-box:50051 --provider OLLAMA --ollama-url http://localhost:11434

# StackSpot enterprise
chatcli connect corp-server:50051 --provider STACKSPOT \
  --client-id myid --client-key mykey --realm mytenant --agent-id myagent

​
Next Steps

Server Mode

Configure the server

Deploy

Deploy with Docker and Helm

K8s Watcher

Monitor Kubernetes