@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, Model, and Reasoning

In interactive TUI mode, the quickest way to change runtime settings is to type one of the shortcut trigger characters at the start of the input line. A picker opens immediately; use ↑/↓ to navigate and Enter to select.

Keyboard cycling shortcuts are also available:

For one-off non-interactive commands, use flags:

# Switch mode for one run
tocodex --mode ask "Explain the authentication flow" -w .
tocodex --mode code "Add validation to the login form" -w .

# Switch model for one run
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

# Set default reasoning effort
tocodex config set reasoningEffort high

# 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

Supported config keys:

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

Auth Commands

Environment Variables

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

Authentication Environment Variables:

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