Skip to content
tcpsystems
Version: Current

CLI quickstart

This guide covers installing the tcp CLI, signing in, and running common commands. For the full command reference, see Command reference.

What the CLI is

Section titled “What the CLI is”

tcp is the tcpsystems suite client: one static Go binary that provides commands for projects, runs, deployments, models, search, and more. It uses OIDC authentication through Pocket ID and speaks both Connect/gRPC and JSON API transports.

Exit codes are part of the contract:

code name meaning
0 ok success
1 error unexpected failure
2 usage bad flag or argument
3 auth not logged in or denied
4 unavailable capability absent or upstream down
5 rate_limited over a documented limit

Install

Section titled “Install”

From source

Section titled “From source”
Terminal window
git clone https://github.com/tcpsystems/cli.git
cd cli
make build

This produces bin/tcp and bin/tcp-mcp in the repository root. Add the bin directory to your PATH, or copy the binary to a location already in your path:

Terminal window
cp bin/tcp /usr/local/bin/tcp

Release artifacts

Section titled “Release artifacts”

Release builds are static binaries for amd64 and arm64. Fetch from the releases page and extract:

Terminal window
# Example for Linux amd64 — adjust the version and platform as needed
curl -sSLO https://github.com/tcpsystems/cli/releases/download/v0.1.0/tcp_0.1.0_linux_amd64.tar.gz
tar xzf tcp_0.1.0_linux_amd64.tar.gz tcp
chmod +x tcp
sudo mv tcp /usr/local/bin/tcp

Verify installation:

Terminal window
tcp version

Authenticate

Section titled “Authenticate”

The CLI uses OIDC device flow via Pocket ID. Run:

Terminal window
tcp login

This prints a code and URL. Open the URL in a browser, enter the code, and complete the sign-in. The credential is stored at ${XDG_STATE_HOME:-~/.local/state}/tcp/token.json with mode 0600.

For machines without a browser, use:

Terminal window
tcp login --no-browser

This prints the URL to copy to another machine. For headless automation, use an API key:

Terminal window
export TCP_STUDIO_KEY_FILE=/path/to/key.json
tcp whoami --check

Verify your identity:

Terminal window
tcp whoami
tcp whoami --check  # makes one authenticated request to prove the credential

To sign out:

Terminal window
tcp logout

First commands

Section titled “First commands”

List projects

Section titled “List projects”
Terminal window
tcp projects list

View live work

Section titled “View live work”
Terminal window
tcp live snapshot

Watch runs

Section titled “Watch runs”
Terminal window
tcp runs watch

List available models

Section titled “List available models”
Terminal window
tcp models list

Run diagnostics

Section titled “Run diagnostics”
Terminal window
tcp doctor

This probes every configured endpoint and reports the live surface.

Common workflows

Section titled “Common workflows”

Start a project run

Section titled “Start a project run”
Terminal window
tcp runs start --project <project-id> --task "Describe the task"

Stream run logs

Section titled “Stream run logs”
Terminal window
tcp runs logs <run-id>

Deploy a project

Section titled “Deploy a project”
Terminal window
tcp deploy start --project <project-id>

Check harness status

Section titled “Check harness status”
Terminal window
tcp harness status --project <project-id>

Machine output

Section titled “Machine output”

Add --json to any command for machine-readable output:

Terminal window
tcp projects list --json

On success, stdout carries one JSON document. On failure, stderr carries {"ok":false,"error":{...}}. Exit codes follow the table above.

Streams emit one JSON object per line:

Terminal window
tcp runs watch --json

Configuration

Section titled “Configuration”

The CLI reads configuration from flags, environment variables, and a config file (default $XDG_CONFIG_HOME/tcp/config.json). Precedence: flag > env > file > default.

Environment variables:

  • TCP_STUDIO_URL: Studio API endpoint
  • TCP_ACUMEN_URL: Acumen gateway endpoint
  • TCP_STATUS_URL: Status endpoint
  • TCP_ISSUER: OIDC issuer (default https://auth.tcp.systems)
  • TCP_TOKEN_FILE: Override credential path
  • TCP_STUDIO_KEY_FILE: API key for machine auth
  • TCP_NON_INTERACTIVE=1: Never prompt; fail with a hint instead

View current configuration:

Terminal window
tcp config show
tcp config path

Troubleshooting

Section titled “Troubleshooting”

“not logged in” or exit code 3

Section titled ““not logged in” or exit code 3”

Run tcp login again. Credentials expire; refresh is transparent but may fail if the token is too old.

“unavailable” or exit code 4

Section titled ““unavailable” or exit code 4”

The requested capability is not served by this deployment, or an upstream is down. Run tcp doctor to identify which endpoint is failing.

“rate_limited” or exit code 5

Section titled ““rate_limited” or exit code 5”

Wait before retrying. The error response may include a retryable hint.

Credential refresh fails

Section titled “Credential refresh fails”

Delete the credential file and re-authenticate:

Terminal window
rm ~/.local/state/tcp/token.json  # or the path from `tcp config path`
tcp login

Next steps

Section titled “Next steps”