@tocodex/cli

Command Line Interface for ToCodex - Run the ToCodex AI coding agent from the terminal without VSCode.

Overview

This CLI uses the @tocodex/vscode-shim package to provide a VSCode API compatibility layer, allowing the main ToCodex extension to run in a Node.js environment.

Installation

npm install -g @tocodex/cli

Requirements:

• Node.js 20 or higher

Updating

tocodex upgrade

Uninstalling

npm uninstall -g @tocodex/cli

Development Installation

For contributing or development:

# From the monorepo root.
pnpm install

# Build the main extension first.
pnpm --filter tocodex bundle

# Build the CLI.
pnpm --filter @tocodex/cli build

Quick Start

1. Get API Key

Get your API key at: https://user.tocodex.com/console/token

2. Configure API Key (One-time Setup)

After installation, a cli-settings.json example file is included in the package directory. You can either:

Option A: Edit the pre-created config file (simplest)

# Find the config file location
tocodex config path

# Edit the cli-settings.json file in your install directory
# Replace "sk-your-api-key-here" with your actual API key

Option B: Use the config command

# Set your ToCodex API key
tocodex config set apiKey sk-your-actual-api-key

# Set provider to tocodex
tocodex config set provider tocodex

# Set default model
tocodex config set model claude-opus-4-7

# Verify your settings
tocodex config list

Settings are saved to ~/.tocodex/cli-settings.json and persist across sessions.

3. Run

# Simple question about a project
tocodex "What is this project?" -w ~/Documents/my-project

# Ask a question (no code changes)
tocodex --mode ask "Explain the authentication flow" -w .

# Code generation / refactoring
tocodex "Add input validation to the login form" -w ~/Documents/my-app

# Architecture review
tocodex --mode architect "Design a caching layer for the API" -w .

# Debug a specific issue
tocodex --mode debug "The API returns 500 on /users endpoint" -w .

# Non-interactive print mode (for scripting / CI)
tocodex --print "Summarize this repo" -w .

# Use a different model for one run
tocodex -m claude-sonnet-4-20250514 "Write unit tests for utils.ts" -w .

# Switch mode for one run
# Common modes: code, ask, architect, debug, browser-worker, ssh-server, image-gen
tocodex --mode ask "Explain this repository" -w .
tocodex --mode code "Refactor the login flow" -w .
tocodex --mode architect "Design a scalable cache layer" -w .

# Persist the default mode for future runs
tocodex config set mode ask
tocodex config set mode code

# Persist the default model for future runs
tocodex config set model gpt-5.5
tocodex config set model claude-sonnet-4-20250514

# Check current persisted settings
tocodex config list

# Run interactively without a prompt (enter prompt in TUI)
tocodex -w ~/Documents/my-project

# One-shot mode (exit after task completion)
tocodex --oneshot "Fix the TypeScript errors" -w .

Switching Mode and Model

Use --mode to switch the agent mode for a single command:

# Ask mode: explanations and read-only answers
tocodex --mode ask "Explain the authentication flow" -w .

# Code mode: implement or modify code
tocodex --mode code "Add validation to the login form" -w .

# Architect mode: design and planning
tocodex --mode architect "Design a retry strategy for API calls" -w .

# Debug mode: troubleshoot errors
tocodex --mode debug "Investigate why /users returns 500" -w .

Use -m or --model to switch the model for a single command:

tocodex -m gpt-5.5 "Review this code" -w .
tocodex --model claude-sonnet-4-20250514 "Write tests for utils.ts" -w .

Persist defaults with tocodex config set:

# Set default mode
tocodex config set mode code
tocodex config set mode ask

# Set default model
tocodex config set model gpt-5.5
tocodex config set model claude-sonnet-4-20250514

# Inspect current defaults
tocodex config list

Scheduled Tasks

ToCodex CLI can create independent scheduled tasks. Tasks are stored locally and can be inspected or run from the command line.

Create a scheduled task

Create an interval task that runs every minute:

tocodex schedule create "Daily news" "Search for and summarize today's major news in Chinese" --trigger '{"kind":"interval","intervalMs":60000}' --mode code

Create a cron task:

tocodex schedule create "Morning summary" "Summarize today's top news" --trigger '{"kind":"cron","expression":"0 9 * * *","timezone":"Asia/Shanghai"}' --mode code

Create a one-time task. runAt is a Unix timestamp in milliseconds:

tocodex schedule create "One-time check" "Check this repository status" --trigger '{"kind":"once","runAt":1760000000000}' --mode code

View scheduled tasks

List all tasks:

tocodex schedule list

List only enabled tasks:

tocodex schedule list --enabled-only

Filter by scope:

tocodex schedule list --scope global
tocodex schedule list --scope workspace

The output is JSON and includes the local task store path, task IDs, enabled status, trigger, nextRunAt, and lastRun.

Run and inspect tasks

Run a task immediately:

tocodex schedule run <task-id>

Show recent run history:

tocodex schedule runs <task-id>
tocodex schedule runs <task-id> --limit 5

Run all currently due tasks once:

tocodex schedule run-due

Update or delete tasks

Update a task with a JSON patch:

tocodex schedule update <task-id> '{"enabled":false}'
tocodex schedule update <task-id> '{"trigger":{"kind":"interval","intervalMs":300000}}'

Delete a task:

tocodex schedule cancel <task-id>

Automatic execution

CLI-created scheduled tasks are executed automatically only while the scheduler daemon is running:

tocodex schedule daemon

The daemon runs in the foreground and checks for due tasks every 30 seconds by default. Keep this terminal/process running if you want CLI-created tasks to execute on schedule.

Use a custom polling interval:

tocodex schedule daemon --poll-ms 10000

Note: The CLI scheduler is not installed as a Windows service, systemd service, or OS-level cron job. If the daemon process is stopped or the terminal is closed, CLI-created scheduled tasks will not run automatically until you start tocodex schedule daemon again. Tasks created by ToCodex's native scheduled-task tools are also checked by a lightweight VS Code extension-side scheduler while the extension host is active.

First Run Without API Key

If you run tocodex without configuring an API key, the CLI will show an interactive onboarding prompt:

1. Connect to ToCodex Cloud — Opens your browser for OAuth authentication
2. Use your own API key — Prompts you to configure your own API key

Note: If a cli-settings.json with a provider value already exists, onboarding is skipped and the CLI uses the configured API key directly.

Configuration

Config Commands

| Command | Description | | -------------------------------- | -------------------------------------- | | tocodex config set <key> <val> | Set a configuration value | | tocodex config get <key> | Get a configuration value | | tocodex config list | List all configuration values | | tocodex config path | Show config file location |

Supported config keys:

| Key | Description | Example | | ---------------- | ---------------------------------------- | -------------------------- | | apiKey | API key for the LLM provider | sk-xxx... | | provider | API provider | tocodex, openrouter | | model | Default model | claude-opus-4-7 | | mode | Default mode | code, ask, architect | | reasoningEffort| Reasoning effort level | medium, high |

Priority Chain

Settings are resolved in this order (first wins):

1. CLI flags (--provider, -m, --api-key, etc.)
2. Config file (~/.tocodex/cli-settings.json)
3. Environment variables (TOCODEX_API_KEY, etc.)
4. Defaults (provider: openrouter, model: claude-opus-4-7)

Config File Example

~/.tocodex/cli-settings.json:

{
  "apiKey": "sk-your-api-key",
  "provider": "tocodex",
  "model": "claude-opus-4-7",
  "mode": "code"
}

API Endpoint

When using the tocodex provider, API requests are sent to:

https://api.tocodex.com

This can be overridden via the TOCODEX_API_URL environment variable.

Usage

Interactive Mode (Default)

By default, the CLI auto-approves actions and runs in interactive TUI mode:

# With config file already set up:
tocodex "What is this project?" -w ~/Documents/my-project

# Or with environment variable:
export TOCODEX_API_KEY=sk-your-key
tocodex "What is this project?" -w ~/Documents/my-project

You can also run without a prompt and enter it interactively in TUI mode:

tocodex -w ~/Documents/my-project

In interactive mode:

• Tool executions are auto-approved
• Commands are auto-approved
• Followup questions show suggestions with a 60-second timeout, then auto-select the first suggestion
• Browser and MCP actions are auto-approved

Approval-Required Mode (--require-approval)

If you want manual approval prompts, enable approval-required mode:

tocodex "Refactor the utils.ts file" --require-approval -w ~/Documents/my-project

In approval-required mode:

• Tool, command, browser, and MCP actions prompt for yes/no approval
• Followup questions wait for manual input (no auto-timeout)

Print Mode (--print)

Use --print for non-interactive execution and machine-readable output:

# Prompt is required
tocodex --print "Summarize this repository"

# Create a new task with a specific session ID (UUID)
tocodex --print --create-with-session-id 018f7fc8-7c96-7f7c-98aa-2ec4ff7f6d87 "Summarize this repository"

Stdin Stream Mode (--stdin-prompt-stream)

For programmatic control (one process, multiple prompts), use --stdin-prompt-stream with --print. Send NDJSON commands via stdin:

printf '{"command":"start","requestId":"1","prompt":"1+1=?"}\n' | tocodex --print --stdin-prompt-stream --output-format stream-json

# Optional: provide taskId per start command
printf '{"command":"start","requestId":"1","taskId":"018f7fc8-7c96-7f7c-98aa-2ec4ff7f6d87","prompt":"1+1=?"}\n' | tocodex --print --stdin-prompt-stream --output-format stream-json

ToCodex Cloud Authentication

To use ToCodex Cloud features (like the provider proxy), you need to authenticate:

# Log in to ToCodex Cloud (opens browser)
tocodex auth login

# Check authentication status
tocodex auth status

# Log out
tocodex auth logout

The auth login command:

1. Opens your browser to authenticate with ToCodex Cloud
2. Receives a secure token via localhost callback
3. Stores the token locally

Tokens are valid for 90 days. The CLI will prompt you to re-authenticate when your token expires.

Authentication Flow:

+----------+       +-----------+       +-----------------+
|   CLI    |       |  Browser  |       |  ToCodex Cloud  |
+----+-----+       +-----+-----+       +--------+--------+
     |                    |                      |
     | Open auth URL      |                      |
     |------------------->|                      |
     |                    |                      |
     |                    | Authenticate          |
     |                    |--------------------->|
     |                    |                      |
     |                    |<---------------------|
     |  Token via callback|                      |
     |<-------------------|                      |
     |                    |                      |
     | Store token        |                      |
     |                    |                      |
+----+-----+       +-----+-----+       +--------+--------+
|   CLI    |       |  Browser  |       |  ToCodex Cloud  |
+----------+       +-----------+       +-----------------+

Options

| Option | Description | Default | | --------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------- | | [prompt] | Your prompt (positional argument, optional) | None | | --prompt-file <path> | Read prompt from a file instead of command line argument | None | | --create-with-session-id <session-id> | Create a new task using the provided session ID (UUID) | None | | -w, --workspace <path> | Workspace path to operate in | Current directory | | -p, --print | Print response and exit (non-interactive mode) | false | | --stdin-prompt-stream | Read NDJSON control commands from stdin (requires --print) | false | | -e, --extension <path> | Path to the extension bundle directory | Auto-detected | | -d, --debug | Enable debug output (includes detailed debug information, prompts, paths, etc) | false | | -a, --require-approval | Require manual approval before actions execute | false | | -k, --api-key <key> | API key for the LLM provider | From env var | | --provider <provider> | API provider (tocodex, anthropic, openai, openrouter, etc.) | openrouter (or tocodex if authenticated) | | -m, --model <model> | Model to use | claude-opus-4-7 | | --mode <mode> | Mode to start in (code, architect, ask, debug, etc.) | code | | --terminal-shell <path> | Absolute shell path for inline terminal command execution | Auto-detected shell | | -r, --reasoning-effort <effort> | Reasoning effort level (unspecified, disabled, none, minimal, low, medium, high, xhigh) | medium | | --consecutive-mistake-limit <n> | Consecutive error/repetition limit before guidance prompt (0 disables the limit) | 10 | | --ephemeral | Run without persisting state (uses temporary storage) | false | | --oneshot | Exit upon task completion | false | | --output-format <format> | Output format with --print: text, json, or stream-json | text |

Auth Commands

| Command | Description | | ---------------------- | ---------------------------------- | | tocodex auth login | Authenticate with ToCodex Cloud | | tocodex auth logout | Clear stored authentication token | | tocodex auth status | Show current authentication status |

Environment Variables

The CLI will look for API keys in environment variables if not provided via --api-key:

| Provider | Environment Variable | | ----------------- | --------------------------- | | tocodex | TOCODEX_API_KEY | | anthropic | ANTHROPIC_API_KEY | | openai-native | OPENAI_API_KEY | | openrouter | OPENROUTER_API_KEY | | gemini | GOOGLE_API_KEY | | vercel-ai-gateway | VERCEL_AI_GATEWAY_API_KEY |

Authentication Environment Variables:

| Variable | Description | | ------------------------- | ----------------------------------------------------------------------- | | TOCODEX_AUTH_BASE_URL | Override the ToCodex Cloud URL (default: https://user.tocodex.com) | | TOCODEX_SDK_BASE_URL | Override the SDK base URL (default: https://cloud-api.tocodex.com) | | TOCODEX_EXTENSION_PATH | Override the extension bundle path |

Architecture

+-------------------+
|   CLI Entry       |
|   (index.ts)      |
+---------+---------+
          |
          v
+-------------------+
|  ExtensionHost    |
|  (extension-      |
|   host.ts)        |
+---------+---------+
          |
     +----+-----+
     |          |
     v          v
+---------+ +------------+
| vscode  | | Extension  |
| shim    | | Bundle     |
+---------+ +------------+

How It Works

1. CLI Entry Point (index.ts): Parses command line arguments and initializes the ExtensionHost

2. ExtensionHost (extension-host.ts):

   • Creates a VSCode API mock using @tocodex/vscode-shim
   • Intercepts require('vscode') to return the mock
   • Loads and activates the extension bundle
   • Manages bidirectional message flow

3. Message Flow:

   • CLI -> Extension: emit("webviewMessage", {...})
   • Extension -> CLI: emit("extensionWebviewMessage", {...})

Development

# Run directly from source (no build required)
pnpm dev --provider tocodex --api-key $TOCODEX_API_KEY --print "Hello"

# Run tests
pnpm test

# Type checking
pnpm check-types

# Linting
pnpm lint

Releasing

# Build + create tarball
node scripts/release.mjs --tarball

# Build + publish to npm
node scripts/release.mjs --npm

# Build + all (tarball + npm + docker)
node scripts/release.mjs --all --version 1.0.0

License

Apache-2.0