CLI reference

Toki ships three executables:

Executable	Purpose
toki	CLI, coordinator, client, daemon and selection helpers
toki-worker	standalone network worker
toki-benchmark	standing benchmark harness

Options that take a value are written --option VALUE. Secrets such as tokens are never passed as arguments; they live in configuration files.

Exit codes

Code	toki	toki client
0	success	success
1	—	the coordinator refused or failed the call, or a summary cannot fit
2	usage error	usage error
125	Toki could not run the command (I/O, configuration or connection failure)	Toki could not be reached or configured

toki local run and toki coordinator run exit with the program's own exit code. toki-worker exits with 2 on a usage error and 1 on a fatal error.

General

toki --version     # or -V
toki help          # or --help, -h
toki roles         # list the roles and the components each hosts

Local runs

toki local run [OPTIONS] -- PROGRAM [ARG...]
toki coordinator run [OPTIONS] -- PROGRAM [ARG...]

local run runs PROGRAM through the combined local daemon, with no coordinator. coordinator run runs it through the coordinator role, which starts store and worker roles as processes of the same executable. Both exit with the program's exit code.

Option	Meaning
--request ID	logical request identity (req-…); minted when omitted
--target NAME	landing target of the supersession key (default local)
--operation NAME	operation of the supersession key (default: the program and its arguments)
--config NAME	configuration of the supersession key (default default)
--attempts N	attempts when the program cannot be started (default 1)
--cwd DIR	working directory for the program

toki local run --cwd ./my-crate -- cargo test

Coordinator: toki build

toki build init --dir DIR --server-name HOST --listen ADDR

Create a private coordinator identity and client configuration in a new directory. Prints the paths of server.json and client.json. Never re-run it to rotate a live identity.

toki build serve --config FILE

Serve the durable build coordinator. Use the server.json from init. The coordinator watches this file for address changes.

toki build configure --config FILE --settings JSON

Apply versioned coordinatorUrl, serverName and listen settings, renewing the certificate name when needed. Prints the public connection publication for clients and workers.

toki build submit  --config FILE --request JSON
toki build get     --config FILE --id ID
toki build cancel  --config FILE --id ID
toki build workers --config FILE
toki build history --config FILE [--limit N] [--before CURSOR]

Submit and inspect builds using the client.json from init. These print full responses; toki client runs the same operations with small summaries.

Client: toki client

toki client OPERATION --config FILE [--view summary|full] [--schema MAJOR.MINOR] [FLAGS]

Operation	Flags
submit	--request FILE (or - for stdin)
get	--id ID
history	--limit N (default 10), --before CURSOR
workers	none
cancel	--id ID
help	lists the operations
schema	prints the schema version, protocol and operations

Output is one line of compact JSON. Errors are one JSON line on stderr. See Client.

Credentials: toki daemon

toki daemon issue  (--socket PATH | --db FILE) --role client|worker --subject NAME
toki daemon revoke (--socket PATH | --db FILE) --role client|worker --subject NAME

issue prints a new token for that principal once. revoke revokes the principal's tokens; revocation is durable before the command returns and is checked on every later call. Use --socket against a running daemon or coordinator, or --db while it is stopped. Credential administration is only available on the protected local endpoint, never remotely.

toki daemon serve --db FILE --socket PATH [--listen ADDR --cert PEM --key PEM]

Serve the transport in this terminal, as the current account, until Ctrl+C. The local endpoint is a Unix socket (its directory must be owned by you with mode 0700) or a Windows named pipe that only the launching user can open. Add --listen, --cert and --key to serve remotely over TLS.

Updates: toki daemon-update

toki daemon-update manage --config FILE
toki daemon-update select --config FILE --desired FILE

manage supervises the coordinator as a child process, applying idle updates and rolling back a release that fails to start. select persists a desired release manifest for it. See Workers.

Selection helpers: toki selection

toki selection toolchain cargo|node [DIR]
toki selection toolchain-output cargo RUSTC_FILE CARGO_FILE
toki selection toolchain-output node NODE_FILE
toki selection digest FILE

Command	Prints
toolchain	the toolchain identity a selection manifest binds, probed in DIR (default .)
toolchain-output	the same identity, computed from saved rustc -vV and cargo -vV (or node --version) output
digest	the digest of a validated toki.selection-manifest

See Dependency selection.

Worker

toki-worker [--config FILE]
toki-worker --help
toki-worker --version
toki worker --config FILE

Connect outward to a TLS coordinator, run assigned commands and reconnect after outages. Without --config, toki-worker reads toki-worker.json. See Workers.

Internal roles

toki worker and toki store without arguments serve a role over standard input and output. They are used by toki coordinator run and are not meant to be started by hand.

Benchmarks: toki-benchmark

toki-benchmark configure PROFILE SOURCE HOST RESERVATION CONFIG [--smoke]
toki-benchmark run smoke|nightly|full CONFIG.json REPORT.json|-
toki-benchmark remote LOCAL.json COMPARISON.json -- TRANSPORT [ARGS...]

The benchmark harness runs native Cargo builds and tests (cold, warm, small edit, link contention and memory pressure) through Toki's worker and accounting, and compares local and remote runs. Its profile currently targets a fixed Rust workspace. Results are raw samples; Toki makes no performance claim until controlled benchmarks support one.

Environment variables

Variable	Used by	Meaning
TOKI_CGROUP_ROOT	worker (Linux)	private delegated cgroup v2 subtree for command containment
TOKI_WORKER_MANAGED	worker	set to 1 by a managing supervisor; the worker then stops when its stdin closes
TOKI_ARTEFACT_<NAME>_MANIFEST, _DIGEST, _PATH	commands	set for a command's declared cross-language artefact inputs; the TOKI_ARTEFACT_ prefix is reserved