# `pythinker` Command

`pythinker` is the main command for Pythinker Code, used to start interactive sessions or execute single queries.

```sh
pythinker [OPTIONS] COMMAND [ARGS]
```

## Basic information

| Option | Short | Description |
|--------|-------|-------------|
| `--version` | `-V` | Show version number and exit |
| `--help` | `-h` | Show help message and exit |
| `--verbose` | | Output detailed runtime information |
| `--debug` | | Log debug information (output to `~/.pythinker/logs/pythinker.log`) |
| `--no-telemetry` | | Disable all anonymous usage telemetry and error reporting (equivalent to setting `PYTHINKER_DISABLE_TELEMETRY=1`) |

## Agent configuration

| Option | Description |
|--------|-------------|
| `--agent NAME` | Use built-in agent, options: `default`, `ask`, `debug`, `okabe` |
| `--agent-file PATH` | Use custom agent file |

`--agent` and `--agent-file` are mutually exclusive. See [Agents and Subagents](../customization/agents.md) for details.

## Configuration files

| Option | Description |
|--------|-------------|
| `--config STRING` | Load TOML/JSON configuration string |
| `--config-file PATH` | Load configuration file (default `~/.pythinker/config.toml`) |

`--config` and `--config-file` are mutually exclusive. Both configuration strings and files support TOML and JSON formats. See [Config Files](../configuration/config-files.md) for details.

## Model selection

| Option | Short | Description |
|--------|-------|-------------|
| `--model NAME` | `-m` | Specify LLM model, overrides default model in config file |

## Working directory

| Option | Short | Description |
|--------|-------|-------------|
| `--work-dir PATH` | `-w` | Specify working directory (default current directory) |
| `--add-dir PATH` | | Add an additional directory to the workspace scope, can be specified multiple times |

The working directory determines the root directory for file operations. Relative paths work within the working directory; absolute paths are required to access files outside it.

`--add-dir` expands the workspace scope to include directories outside the working directory, making all file tools able to access files in those directories. Added directories are persisted with the session state. You can also add directories at runtime via the [`/add-dir`](./slash-commands.md#add-dir) slash command.

## Session management

| Option | Short | Description |
|--------|-------|-------------|
| `--continue` | `-C` | Continue the previous session in the current working directory |
| `--session [ID]` / `--resume [ID]` | `-S` / `-r` | Resume a session. With ID: resume that session (creates new if not found). Without ID: open interactive session picker (shell mode only) |

`--continue` and `--session`/`--resume` are mutually exclusive.

## Input and commands

| Option | Short | Description |
|--------|-------|-------------|
| `--prompt TEXT` | `-p` | Pass user prompt, doesn't enter interactive mode |
| `--command TEXT` | `-c` | Alias for `--prompt` |

When using `--prompt` (or `--command`), Pythinker Code exits after processing the query (unless `--print` is specified, results are still displayed in interactive mode).

## Loop control

| Option | Description |
|--------|-------------|
| `--max-steps-per-turn N` | Maximum steps per turn, overrides `loop_control.max_steps_per_turn` in config file |
| `--max-retries-per-step N` | Maximum retries per step, overrides `loop_control.max_retries_per_step` in config file |
| `--max-ralph-iterations N` | Number of iterations for Ralph Loop mode; `0` disables; `-1` is unlimited |

### Ralph Loop

[Ralph](https://ghuntley.com/ralph/) is a technique that puts an agent in a loop: the same prompt is fed again and again so the agent can keep iterating one big task.

When `--max-ralph-iterations` is not `0`, Pythinker Code enters Ralph Loop mode and automatically loops through task execution until the agent outputs `<choice>STOP</choice>` or the iteration limit is reached.

## UI modes

| Option | Description |
|--------|-------------|
| `--print` | Run in print mode (non-interactive), implicitly enables `--auto` |
| `--quiet` | Shortcut for `--print --output-format text --final-message-only` |
| `--acp` | Run in ACP server mode (deprecated, use `pythinker acp` instead) |
| `--wire` | Run in Wire server mode (experimental) |

The four options are mutually exclusive, only one can be selected. Default is shell mode. See [Print Mode](../customization/print-mode.md) and [Wire Mode](../customization/wire-mode.md) for details.

## Print mode options

The following options are only effective in `--print` mode:

| Option | Description |
|--------|-------------|
| `--input-format FORMAT` | Input format: `text` (default) or `stream-json` |
| `--output-format FORMAT` | Output format: `text` (default) or `stream-json` |
| `--final-message-only` | Only output the final assistant message |

`stream-json` format uses JSONL (one JSON object per line) for programmatic integration.

## MCP configuration

| Option | Description |
|--------|-------------|
| `--mcp-config-file PATH` | Load MCP config file, can be specified multiple times |
| `--mcp-config JSON` | Load MCP config JSON string, can be specified multiple times |

Default loads `~/.pythinker/mcp.json` (if exists). See [Model Context Protocol](../customization/mcp.md) for details.

## Approval control

| Option | Short | Description |
|--------|-------|-------------|
| `--yolo` | `-y` | Dangerously skip permission approvals (user still reachable for `AskUserQuestion`) |
| `--yes` | | Alias for `--yolo` |
| `--auto-approve` | | Alias for `--yolo` |
| `--no-yolo` | | Force YOLO off for this run, overriding `--yolo`, config `default_yolo`, and any persisted/resumed YOLO state |
| `--auto` | | Auto mode: auto-dismiss `AskUserQuestion`, and auto-approve tool calls when the current trust/safe-mode policy permits (otherwise approval-required actions fail closed). Use when no user will be at the terminal |

::: warning Note
In YOLO or auto mode, all file modifications and shell commands are automatically executed. Use with caution.
:::

## Plan mode

| Option | Description |
|--------|-------------|
| `--plan` | Start a new session in plan mode |

When started with `--plan`, the AI can only use read-only tools to explore the codebase and write an implementation plan. When resuming an existing session, `--plan` forces plan mode on; resuming without `--plan` preserves the session's existing state.

You can also set `default_plan_mode = true` in the config file to start new sessions in plan mode by default. See [Configuration files](../configuration/config-files.md).

## Thinking mode

| Option | Description |
|--------|-------------|
| `--thinking` | Enable thinking mode |
| `--no-thinking` | Disable thinking mode |
| `--thinking-effort LEVEL` | Thinking effort level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (alias `--thinking-level`) |

Thinking mode requires model support. If not specified, uses the last session's setting.

## Skills configuration

| Option | Description |
|--------|-------------|
| `--skills-dir PATH` | Append additional skills directories (repeatable) |

When not specified, Pythinker Code automatically discovers user-level and project-level skills directories in priority order. See [Agent Skills](../customization/skills.md) for details.

## Subcommands

| Subcommand | Description |
|------------|-------------|
| [`pythinker login`](#pythinker-login) | Log in to your Pythinker account |
| [`pythinker logout`](#pythinker-logout) | Log out from your Pythinker account |
| [`pythinker info`](./pythinker-info.md) | Display version and protocol information |
| [`pythinker acp`](./pythinker-acp.md) | Start multi-session ACP server |
| [`pythinker mcp`](./pythinker-mcp.md) | Manage MCP server configuration |
| [`pythinker plugin`](../customization/plugins.md) | Manage plugins (Beta) |
| [`pythinker term`](./pythinker-term.md) | Launch the Toad terminal UI |
| [`pythinker export`](#pythinker-export) | Export a session as a ZIP file |
| [`pythinker dashboard`](./pythinker-dashboard.md) | Launch the Agent Tracing Visualizer (Technical Preview) |
| [`pythinker web`](./pythinker-web.md) | Start the Web UI server |

### `pythinker login`

Log in to your Pythinker account. This automatically opens a browser; complete account authorization and available models will be automatically configured.

```sh
pythinker login
```

### `pythinker logout`

Log out from your Pythinker account. This clears stored OAuth credentials and removes related configuration from the config file.

```sh
pythinker logout
```

### `pythinker export`

Export session data as a ZIP file. The ZIP contains all files in the session directory (`context.jsonl`, `wire.jsonl`, `state.json`, etc.) and related diagnostic logs.

```sh
pythinker export [<session_id>] [-o <output_path>] [--yes]
```

| Argument / Option | Description |
|--------|-------------|
| `<session_id>` | Session ID to export. If omitted, the CLI previews the previous session for the current working directory and asks for confirmation before exporting |
| `--output, -o` | Output ZIP file path (defaults to `session-<id>.zip` in the current directory) |
| `--yes, -y` | Skip the confirmation prompt when exporting the default previous session |
| `--format` | Transcript format; only `yaml` is accepted (the transcript is always included as YAML) |

::: info Added
Added in version 1.20.
:::

### `pythinker dashboard`

::: warning Note
Technical Preview feature, may be unstable.
:::

Launch the Agent Tracing Visualizer to view and analyze session traces in a browser.

```sh
pythinker dashboard [OPTIONS]
```

| Option | Short | Description |
|--------|-------|-------------|
| `--host TEXT` | `-H` | Host address to bind to (default: `127.0.0.1`) |
| `--network` | `-n` | Listen on all network interfaces (bind to `0.0.0.0`) with auto-detected LAN IP display |
| `--port INTEGER` | `-p` | Port number to bind to (default: `5495`) |
| `--open / --no-open` | | Automatically open browser (default: enabled) |
| `--reload` | | Enable auto-reload (development mode) |

See [Agent Tracing Visualizer](./pythinker-dashboard.md) for details.

### `pythinker web`

Start the Web UI server to access Pythinker Code through a browser.

```sh
pythinker web [OPTIONS]
```

If the default port is in use, the server will pick the next available port (by default `5494`–`5503`) and print a notice in the terminal.

| Option | Short | Description |
|--------|-------|-------------|
| `--host TEXT` | `-H` | Host address to bind to (default: `127.0.0.1`) |
| `--network` | `-n` | Listen on all network interfaces (bind to `0.0.0.0`) with auto-detected LAN IP display |
| `--port INTEGER` | `-p` | Port number to bind to (default: `5494`) |
| `--reload` | | Enable auto-reload (development mode) |
| `--open / --no-open` | | Automatically open browser (default: enabled) |

Examples:

```sh
# Default startup, automatically opens browser
pythinker web

# Specify port
pythinker web --port 8080

# Don't automatically open browser
pythinker web --no-open

# Bind to all network interfaces (allow LAN access)
pythinker web --host 0.0.0.0
```

See [Web UI](./pythinker-web.md) for details.
