CLI Reference

tokst is an advanced device tool. It connects local Agent endpoints, reports their health, and supports explicit Session and task operations. Agents use Cloud MCP for memory, search, context, and memory governance.

Start Here

tokst login
tokst start
tokst auto on --agent all
tokst status
tokst doctor

login authorizes the device in a browser and creates the minimum local credential configuration. start connects the device and starts its service. auto on is an explicit opt-in for automatic Session capture and installs the selected bridge. status shows this device's Runtime connection and its Agents across accessible workspaces. Use auto status for capture and bridge diagnostics. doctor reports recovery actions for connection or integration issues.

Device Commands

Use tokst --help for the concise command list. tokst <group> --help provides the full reference for session, task, and agent.

Local directory behavior

Installation adds only the verified binary and PATH entry. login creates ~/.tokst/config.json; start creates the private service queue and logs. Each created Agent uses its own ~/.tokst/workspace/bindings/<binding-id>/work/ directory. Project directories require an explicit user selection and stay on the device; Cloud receives only a route hash.

tokst init is the only command that creates a project-local .tokst/ directory, Agent guidance, or project MCP configuration.

Sessions

Sessions capture a bounded piece of work that needs meaningful checkpoints, evidence, or a durable outcome. Automatic bridges also create Session records from supported endpoint activity.

tokst session start --task "Review deployment readiness" --json
tokst session capture --session <session-id> "Verified the staging checklist" --json
tokst session checkpoint --session <session-id> "Deployment approval pending" --json
tokst session finalize --session <session-id> "Approval completed" --json
tokst session list --json
tokst session candidates --json

Session records retain meaningful evidence and diagnostics. tokst session candidates lists existing review candidates during the compatibility window. Cloud MCP remains the primary interface for resulting durable memory and shared context.

Tasks

Create and assign formal tasks in the Dashboard. The CLI inspects and controls tasks from an authenticated device or endpoint.

tokst task list --json
tokst task show <task-id> --json
tokst task claim <task-id> --endpoint <endpoint-id> --json
tokst task cancel <task-id> --reason "No longer required" --json
tokst task retry <task-id> --endpoint <endpoint-id> --mode automatic --json

Task commands preserve assignment, claim, execution, result, cancellation, and retry audit history. Use the Dashboard for task creation, multi-endpoint assignment, review, and archive actions.

Workspace and Atlas Governance

Use the Dashboard for human administration and Cloud MCP for Agent operations. Cloud MCP provides the governed Workspace and Atlas tools, including archival and restore. The CLI keeps device Runtime operations separate from shared data.

Runtime Delivery and Communication

tokst start maintains the authenticated WSS connection used by Task delivery and Communication. The Runtime routes each event to the selected Agent binding, queues offline delivery, streams reply activity, and persists the final result through the Server.

tokst status --json
tokst doctor
tokst logs

Use Dashboard -> Communication for long-lived direct chats and Agent groups. Use Dashboard -> Tasks for explicitly assigned work. TOKST_AGENT=1 or --agent remains available for bounded machine-readable diagnostics; add --full for complete JSON.

Retired Local mode

TokST Local is retired. Existing device files remain untouched, while the CLI no longer opens, exports, restores, synchronizes, or serves Local SQLite profiles. Connected Runtime devices retain only an internal encrypted queue for sanitized delivery recovery. See TokST Local retirement.

Memory Interface

Cloud MCP at https://api.tokst.com/mcp is the only active interface for memory, search, context, files, Workspaces, and Atlases. See the MCP reference for tools and Agent setup for connection instructions.

Authentication and Updates

curl -fsSLo tokst-install.sh https://tokst.com/install.sh
sh tokst-install.sh
tokst login
tokst version --verbose
tokst update

For CI or an unattended service, use a dedicated API key through protected configuration:

tokst login --key tk_live_your_api_key
tokst connection test
tokst logout

Keep API keys, private keys, cookies, and tokens out of source code, shell history, and durable memory records.