> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Connection (chatcli connect)

> Connect your local terminal to a remote ChatCLI server via gRPC to access AI from anywhere.

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

<Steps>
  <Step title="Connect to the server">
    ```bash theme={"system"}
    # Connect using positional address
    chatcli connect myserver:50051

    # Connect with explicit flag
    chatcli connect --addr myserver:50051
    ```
  </Step>

  <Step title="Verify server information">
    Upon connecting, ChatCLI displays server information:

    ```text theme={"system"}
    Connected to ChatCLI server (version: 1.2.0, provider: CLAUDEAI, model: claude-sonnet-4-6)
    ```

    If the server has an active K8s Watcher, it also shows:

    ```text theme={"system"}
    K8s watcher active: deployment/myapp in namespace/production (context injected into all prompts)
    ```
  </Step>
</Steps>

***

## All Flags

| Flag                 | Description                                      | Env Var                  |
| -------------------- | ------------------------------------------------ | ------------------------ |
| `--addr <host:port>` | Server address                                   | `CHATCLI_REMOTE_ADDR`    |
| `--token <string>`   | Authentication token                             | `CHATCLI_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-auth`   | Uses OAuth credentials from the local auth store |                          |
| `--tls`              | Enables TLS connection                           |                          |
| `--ca-cert <path>`   | CA certificate for TLS verification              |                          |
| `-p <prompt>`        | One-shot mode: send prompt and exit              |                          |
| `--raw`              | Raw output (no Markdown/ANSI formatting)         |                          |
| `--max-tokens <int>` | Maximum tokens in response                       |                          |

### StackSpot Flags

| Flag           | Description            |
| -------------- | ---------------------- |
| `--client-id`  | StackSpot Client ID    |
| `--client-key` | StackSpot Client Key   |
| `--realm`      | StackSpot Realm/Tenant |
| `--agent-id`   | StackSpot Agent ID     |

### Ollama Flags

| Flag           | Description                                |
| -------------- | ------------------------------------------ |
| `--ollama-url` | Ollama base URL (e.g., `http://gpu:11434`) |

***

## Credential Modes

You can choose how to authenticate with the LLM provider:

<Tabs>
  <Tab title="Server Credentials">
    Do not send any credential flags. The server uses its own API keys:

    ```bash theme={"system"}
    chatcli connect myserver:50051
    ```
  </Tab>

  <Tab title="Your Own API Key">
    Send your key directly. The server uses it to make the LLM call:

    ```bash theme={"system"}
    chatcli connect myserver:50051 --provider OPENAI --llm-key sk-my-key
    ```
  </Tab>

  <Tab title="Local OAuth">
    Use OAuth credentials already saved locally (from `/auth login`):

    ```bash theme={"system"}
    # Prerequisite: have completed OAuth login
    # /auth login anthropic  (inside interactive chatcli)

    # Connect using those credentials
    chatcli connect myserver:50051 --use-local-auth

    # With a specific provider
    chatcli connect myserver:50051 --use-local-auth --provider CLAUDEAI
    ```

    The `--use-local-auth` flag reads the OAuth token from `~/.chatcli/auth-profiles.json` and sends it to the server. If you don't specify `--provider`, ChatCLI tries Anthropic first, then OpenAI.
  </Tab>

  <Tab title="StackSpot">
    ```bash theme={"system"}
    chatcli connect myserver:50051 --provider STACKSPOT \
      --client-id <id> --client-key <key> --realm <realm> --agent-id <agent>
    ```
  </Tab>

  <Tab title="Ollama">
    ```bash theme={"system"}
    chatcli connect myserver:50051 --provider OLLAMA --ollama-url http://gpu-server:11434
    ```
  </Tab>
</Tabs>

***

## One-Shot Mode via Connect

Send a single prompt to the remote server and receive the response:

```bash theme={"system"}
# 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:

```bash theme={"system"}
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 commands**: `/status`, `/plugins list`, `/agents list`, `/skills list`

***

## Remote Resource Discovery

Upon connecting, the client automatically discovers plugins, agents, and skills available on the server:

```text theme={"system"}
Connected to ChatCLI server (version: 1.3.0, provider: CLAUDEAI, model: claude-sonnet-4-6)
 Server has 3 plugins, 2 agents, 4 skills available
```

<Tabs>
  <Tab title="Remote Plugins">
    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:

    ```text theme={"system"}
    # List plugins (local + remote)
    /plugin list

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

  <Tab title="Remote Agents and Skills">
    Server agents and skills are transferred to the client and composed locally, allowing merging with local resources:

    ```text theme={"system"}
    # List agents (local + remote)
    /agent list

    Available Agents:
      * go-expert       - Go/Golang Specialist                  [local]
      * devops-senior   - Senior DevOps with K8s focus          [remote]

    # Load a remote agent
    /agent load devops-senior
    ```
  </Tab>
</Tabs>

### 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:

```bash theme={"system"}
# In interactive mode
/watch status
```

Example output:

```text theme={"system"}
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:

```bash theme={"system"}
# In your .bashrc or .zshrc
export CHATCLI_REMOTE_ADDR=myserver:50051
export CHATCLI_REMOTE_TOKEN=my-token

# Now just:
chatcli connect
```

***

## TLS and Security

<Steps>
  <Step title="Insecure Connection (Development)">
    ```bash theme={"system"}
    chatcli connect localhost:50051
    ```

    <Warning>
      When TLS is disabled, a **warning is logged** by the client as a reminder that the connection is not encrypted. In production, enable TLS.
    </Warning>
  </Step>

  <Step title="Connection with TLS">
    ```bash theme={"system"}
    chatcli connect myserver:50051 --tls

    # With custom CA certificate
    chatcli connect myserver:50051 --tls --ca-cert /path/to/ca.pem
    ```
  </Step>

  <Step title="Token + TLS (Production)">
    ```bash theme={"system"}
    chatcli connect myserver:50051 --tls --token my-secret-token
    ```
  </Step>
</Steps>

<Info>
  For a complete security guide (authentication, container hardening, RBAC, etc.), see the [security documentation](/features/security).
</Info>

***

## 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

```bash theme={"system"}
# 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

<CardGroup cols={2}>
  <Card title="Server Mode" icon="server" href="/features/server-mode">
    Configure the server
  </Card>

  <Card title="Deploy" icon="docker" href="/getting-started/docker-deployment">
    Deploy with Docker and Helm
  </Card>

  <Card title="K8s Watcher" icon="binoculars" href="/features/k8s-watcher">
    Monitor Kubernetes
  </Card>
</CardGroup>