CodeTorch.CLI 7.1.241

CodeTorch CLI

Command-line tool for managing AI coding tasks in the CodeTorch portal.

Documentation

• Agent Guide - Comprehensive guide for AI agents using the CLI
• Troubleshooting - Known issues and solutions
• Specification - Design specification and API details

Installation

dotnet tool install --global CodeTorch.CLI

For cloud coding environments, use the install script that matches the machine:

curl -fsSL https://raw.githubusercontent.com/PhilOchu/codetorch/main/tools/cli/scripts/install-ctc.sh | bash

The Linux installer installs the latest published CLI by default and adds ctc to the current session PATH plus common shell profiles. Pin a version only when you need a controlled rollback or rollout:

curl -fsSL https://raw.githubusercontent.com/PhilOchu/codetorch/main/tools/cli/scripts/install-ctc.sh | CODETORCH_CLI_VERSION=7.1.6 bash

irm https://raw.githubusercontent.com/PhilOchu/codetorch/main/tools/cli/scripts/install-ctc.ps1 | iex

Quick Start

# Configure environment and API key
ctc config env prod
ctc config set api-key <your-api-key>
ctc config set org <organization-id>

# Submit a task and monitor progress (exits at approval gates)
ctc run "Fix the login bug" --org <org-id> --repo <repo-id>

# Submit with automatic approval of all gates
ctc run "Fix the login bug" --org <org-id> --repo <repo-id> --auto-approve

# Or use individual commands
ctc task get "#123" --org <org-id> --stages
ctc task messages "#123" --org <org-id>
ctc task approve "#123" --org <org-id>

Cloud Tool Gateway

Cloud agents can use scoped tool grants without a full CodeTorch user API key.

export CODETORCH_API_URL=https://<portal-api>
export CODETORCH_TOOL_TOKEN=ctg_xxx

ctc tool db targets
ctc tool db schema dev-catalog
ctc tool db query dev-catalog --sql "select top 10 * from dbo.Users"
ctc tool log targets
ctc tool log query app-dev --search "error"
ctc tool devslot targets

Create grants from an authenticated operator session:

ctc tool grant create claude-dev --org <org-id> --expires-days 7 --db dev-catalog=<environment-id>:<database-id>:ro
ctc tool grant create claude-preview --org <org-id> --devslot api=<workspace-id>:api:"Tenant API Slot"
ctc tool grant list --org <org-id>
ctc tool grant revoke <grant-id> --org <org-id>

Commands

Configuration

Resources

Automation Inventory

Inventory commands are read-only and return structured JSON. show and export include 20 recent runs by default; pass --runs 0 to omit run history. Export refuses to overwrite a file unless --force is supplied.

Task Operations

Goal Operations

Other

Tool Gateway

Tool gateway read commands support agent-friendly output:

ctc tool db targets --json
ctc tool log targets --plain
ctc tool capabilities --json
ctc tool devslot targets --json
ctc tool db query dev-catalog --sql "select top 5 name from sys.tables" --json

When stdout is redirected, tool gateway commands automatically use plain text instead of terminal table rendering.

Exit Codes (ctc run)

Configuration

Configuration is stored in ~/.codetorch/config.json.

Environment Variables (override config file):

• CODETORCH_API_KEY - API key
• CODETORCH_API_URL - API URL
• CODETORCH_ENV - Environment name
• CODETORCH_TOOL_TOKEN - Scoped tool grant token for ctc tool db and ctc tool log
• CODETORCH_CLI_VERSION - Optional CLI version used by install scripts

Note: Environment variables take precedence over config file. See Troubleshooting for common issues.

Confirmation Behavior

Destructive commands (approve, request-changes, cancel, archive, retry) are agent-first: invoking the command is treated as intent.

Use --confirm when you want the old require-explicit-yes behavior regardless of environment.

Task ID Formats

Both formats work:

• #123 - Task number (easier to use)
• 5835baea-c48a-4101-9974-0b414a89967a - Full GUID

Requirements

• .NET 10.0 Runtime or later