CLI Reference

synti-cli is the terminal client for Synti. It connects over WebSocket (ws:// or wss://) to a running headless server and lets you list workspaces, drive sessions, and stream agent responses from scripts and CI.

For a gentler, task-oriented walkthrough of connecting the client, see CLI Client. This page is the exhaustive flag reference.

Prerequisites

Bun runtime installed.
For run and --validate-server: an API key via --api-key, $LLM_API_KEY, or a provider-specific variable (e.g. $ANTHROPIC_API_KEY).
For every other command: a running Synti headless server with a URL and token.

Installation

# Option A: run directly from the workspace
bun run apps/cli/src/index.ts <command>

# Option B: link globally (adds synti-cli to your PATH)
cd apps/cli && bun link
synti-cli <command>

Quick start

The fastest way to try it — no server setup needed. The run command spawns its own server:

ANTHROPIC_API_KEY=sk-... synti-cli run "Hello, world!"

Connection options

Flag	Env var	Default	Description
`--url <ws[s]://...>`	`SYNTI_SERVER_URL`	—	Server WebSocket URL
`--token <secret>`	`SYNTI_SERVER_TOKEN`	—	Authentication token
`--workspace <id>`	—	auto-detect	Workspace ID
`--timeout <ms>`	—	`10000`	Request timeout
`--tls-ca <path>`	`SYNTI_TLS_CA`	—	Custom CA cert for self-signed TLS
`--json`	—	`false`	Raw JSON output for scripting
`--send-timeout <ms>`	—	`300000`	Timeout for the `send` command (5 min)

Flags take precedence over environment variables. If --workspace is omitted, the CLI auto-detects the first available workspace.

Commands

Info & health

synti-cli ping              # Verify connectivity (clientId + latency)
synti-cli health            # Check credential store health
synti-cli versions          # Show server runtime versions

Resource listing

synti-cli workspaces        # List all workspaces
synti-cli sessions          # List sessions in the workspace
synti-cli connections       # List LLM connections
synti-cli sources           # List configured sources

Session operations

synti-cli session create [--name <n>] [--mode <m>]   # Create a session
synti-cli session messages <id>                       # Print message history
synti-cli session delete <id>                         # Delete a session
synti-cli cancel <id>                                 # Cancel processing

Send a message (streaming)

# Send a message and stream the agent response in real time
synti-cli send <session-id> <message>

# Pipe text from stdin
echo "Summarize this file" | synti-cli send <session-id>

# Read from stdin explicitly
cat document.txt | synti-cli send <session-id> --stdin

The send command subscribes to session events and streams them to stdout:

text_delta — text streamed inline
tool_start — [tool: name] marker
tool_result — tool output (truncated to 200 chars)
error — printed to stderr, exit code 1
complete — exit code 0
interrupted — exit code 130

Power user

# Raw RPC call — send any channel with JSON args
synti-cli invoke <channel> [json-args...]

# Subscribe to push events (Ctrl+C to stop)
synti-cli listen <channel>

Examples:

synti-cli invoke system:homeDir
synti-cli invoke sessions:get '"workspace-123"'
synti-cli listen session:event

Run (self-contained)

synti-cli run <prompt>
synti-cli run --workspace-dir ./project --source github "List open PRs"

The run command is fully self-contained — it spawns a headless server, creates a session, sends the prompt, streams the response, and exits. No separate server setup needed. An API key is resolved from --api-key, $LLM_API_KEY, or a provider-specific variable (e.g. $ANTHROPIC_API_KEY, $OPENAI_API_KEY).

Flag	Default	Description
`--workspace-dir <path>`	—	Register a workspace directory before running
`--source <slug>`	—	Enable a source (repeatable)
`--output-format <fmt>`	`text`	Output format: `text` or `stream-json`
`--mode <mode>`	`allow-all`	Permission mode for the session
`--no-cleanup`	`false`	Skip session deletion on exit
`--server-entry <path>`	—	Custom server entry point

LLM configuration:

Flag	Env fallback	Default	Description
`--provider <name>`	`LLM_PROVIDER`	`anthropic`	Provider: `anthropic`, `openai`, `google`, `openrouter`, `groq`, `mistral`, `xai`, etc.
`--model <id>`	`LLM_MODEL`	(provider default)	Model ID (e.g. `claude-sonnet-4-5-20250929`, `gpt-4o`, `gemini-2.0-flash`)
`--api-key <key>`	`LLM_API_KEY`	(provider env)	API key — also checks provider-specific vars like `$OPENAI_API_KEY`
`--base-url <url>`	`LLM_BASE_URL`	—	Custom endpoint for proxies, OpenRouter, or self-hosted models

# Multi-provider examples
synti-cli run --provider openai --model gpt-4o "Summarize this repo"
GOOGLE_API_KEY=... synti-cli run --provider google --model gemini-2.0-flash "Hello"
synti-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"

The prompt can also be piped via stdin:

echo "Summarize this file" | synti-cli run
cat error.log | synti-cli run "What's causing these errors?"

Validate server

# Against a running server
synti-cli --validate-server --url ws://127.0.0.1:9100 --token <token>

# Self-contained (auto-spawns a server)
synti-cli --validate-server

When no --url is provided, --validate-server automatically spawns a local headless server (the same way run does), runs the validation, and shuts it down. It exercises a full server-lifecycle integration test — connect/handshake, credential health check, workspace and session listing, message streaming, tool use, and temporary source and skill creation — cleaning up every resource it creates on completion. Use --json for machine-readable output.

--validate-server mutates workspace state while it runs: it creates and deletes a temporary session, source, and skill. All of them are removed when the run finishes.

Scripting patterns

# Get workspace IDs
WORKSPACES=$(synti-cli --json workspaces | jq -r '.[].id')

# Count sessions per workspace
for ws in $WORKSPACES; do
  COUNT=$(synti-cli --json --workspace "$ws" sessions | jq length)
  echo "$ws: $COUNT sessions"
done

# Create a session and capture its ID
SESSION_ID=$(synti-cli --json session create --name "CI Run" | jq -r '.id')

# Send a message and wait for completion
synti-cli send "$SESSION_ID" "Run the test suite and report results"

# Clean up
synti-cli session delete "$SESSION_ID"

TLS / wss://

For remote servers with TLS:

# Trusted certificate (Let's Encrypt, etc.)
synti-cli --url wss://server.example.com:9100 ping

# Self-signed certificate
synti-cli --url wss://server.example.com:9100 --tls-ca /path/to/ca.pem ping

The --tls-ca flag sets NODE_EXTRA_CA_CERTS before connecting. You can also set SYNTI_TLS_CA in your environment.

Troubleshooting

Symptom	Cause	Fix
`Connection timeout`	Server not running or unreachable	Check the server is started; verify the URL
`AUTH_FAILED`	Wrong token	Check `SYNTI_SERVER_TOKEN` matches the server
`PROTOCOL_VERSION_UNSUPPORTED`	Version mismatch	Update the CLI and server to the same version
`WebSocket connection error`	Network issue or TLS problem	For self-signed certs, use `--tls-ca`
`No workspace available`	Workspace not yet created	Create one via the desktop app or API

​Prerequisites

​Installation

​Quick start

​Connection options

​Commands

​Info & health

​Resource listing

​Session operations

​Send a message (streaming)

​Power user

​Run (self-contained)

​Validate server

​Scripting patterns

​TLS / wss://

​Troubleshooting

Prerequisites

Installation

Quick start

Connection options

Commands

Info & health

Resource listing

Session operations

Send a message (streaming)

Power user

Run (self-contained)

Validate server

Scripting patterns

TLS / wss://

Troubleshooting