# PawCode CLI

PawCode is the terminal client for PawFlow. It connects to the same backend and conversations as the web UI and VS Code extension. PawCode is chat-only: relay lifecycle is managed by webchat server resources or the standalone PawFlow Relay client.

## Quick Start

```bash
python -m pawflow_cli --dir .

# Or with an explicit server
PAWFLOW_SERVER=http://localhost:PORT python -m pawflow_cli --dir .
```

PawCode opens the browser for OAuth login when needed, then connects as a conversation client. Start filesystem access separately with `pawflow-relay` or from the webchat resource panel.

## Server And Private Gateway

Use an explicit server URL whenever you are not targeting the default local development port:

```bash
PAWFLOW_SERVER="https://localhost:19990" pawcode --dir .
```

For a server protected by Private Gateway, pass the gateway key through the environment or the CLI option. PawCode exchanges it for the gateway cookie before normal auth/API/SSE calls:

```bash
PAWFLOW_SERVER="https://pawflow.example.com" \
PAWFLOW_GATEWAY_KEY="your-private-gateway-key" \
pawcode --dir .

# Equivalent explicit flag
pawcode --server "https://pawflow.example.com" --gateway-key "your-private-gateway-key" --dir .
```

Keep the gateway key in your shell profile or secret manager. Do not paste it into conversation prompts.

## Standalone Installer Builds

PawCode can be packaged as a standalone terminal binary with PyInstaller:

```bash
python -m pip install pyinstaller
python scripts/build-pawcode-installer.py
```

The build writes artifacts under `dist/pawcode-installers/`. Every platform gets a portable archive with the `pawcode` binary and install scripts. On Linux, the builder also creates a `.deb` when `dpkg-deb` is available. On macOS, it creates a `.pkg` when `pkgbuild` is available. On Windows, it creates an NSIS setup executable when `makensis` is available; otherwise the generated zip still contains `install.ps1`.

The standalone binary keeps PawCode's existing behavior: it stores sessions under `~/.pawflow`, honors `PAWFLOW_SERVER`, supports `pawcode auth login`, and can run stream-JSON mode. It does not bundle or manage `pawflow-relay`.

## What PawCode Adds

- streaming chat with Rich markdown rendering;
- access to conversations that may already have linked relays;
- the same conversation store as the web UI;
- multi-agent streaming and active-agent status;
- approval dialogs for sensitive actions;
- colored diffs and git-oriented workflows;
- command completion and history search;
- stream-JSON compatibility for Claude-Code-style integrations.

## Common Commands

| Command | Purpose |
|---|---|
| `/new [agent] [--llm svc] [--relay rid] [--title text]` | Create a new conversation with an agent, LLM service, optional relay binding, and optional title. |
| `/conv` | List conversations. |
| `/resume <id>` | Resume an existing conversation. |
| `/agent list|create|delete|select` | Manage agents. |
| `/msg <agent|ALL> <text>` | Send to a specific agent or all agents. |
| `/btw <agent> <question>` | Ask a side question without interrupting main work. |
| `/interrupt [agent]` | Interrupt an agent without force-stopping it. |
| `/stop [agent]` | Force-stop an agent immediately. |
| `/run <command>` | Execute through the conversation's linked relay, if one exists. |
| `/terminal` | Run terminal commands through a linked relay, if available. |
| `/diff` | Show git diff through a linked relay, if available. |
| `/plan <description>` | Enter plan mode. |
| `/call <tool> ...` | Invoke a PawFlow tool directly. |
| `/explore` | Browse files interactively. |
| `/compact` | Compact conversation context. |
| `/model <name>` | Switch model where supported. |
| `/cost` | Show token/cost usage. |

## Shared Conversations

PawCode does not create a separate silo. A conversation can be opened in the web UI, continued in PawCode, and then inspected in VS Code. Events are streamed through the same backend and persisted through the conversation store.

`/new` uses the same server-side `create_conversation` action as webchat. If no agent is provided, PawCode uses the first available agent definition and picks a matching `{agent}_llm_service` when present, otherwise the first enabled `llmConnection` service. Use `--relay` to link a relay at creation time; the first relay passed becomes the default relay for the conversation.

## Stream JSON Mode

PawCode can be used as a stream-JSON frontend for tooling that expects Claude-Code-style input/output:

```bash
echo '{"type":"user","message":{"role":"user","content":"hello"}}' | \
  pawcode --input-format stream-json --output-format stream-json
```

## Relay Behavior

PawCode no longer starts or stops relays. Filesystem, grep/glob, edit, shell, screen, and project graph tools operate through relays already linked to the conversation by the server/webchat or the standalone relay client. See `docs/relay_client.md` for client relay setup.
