Command Reference

This page documents all available Tektii CLI commands, their arguments, and options.

config vs scenario: a preset vs a run of it

A config is a reusable, saved preset — the subscriptions, window, and capital, stored under your account as an id. A scenario is a concrete run instance of a config against a strategy version, and launching one starts a backtest (it returns a scenario id at QUEUED). So config create saves a preset for later, while scenario run starts a run — either from a saved config id or from a one-shot config file.

Global Options

These options apply to all commands:

Option	Environment Variable	Description	Default
`--api-url <URL>`	`TEKTII_API_URL`	API endpoint	`https://api.tektii.com`
`--api-key <KEY>`	`TEKTII_API_KEY`	API authentication key	Required (except `strategy init`)
`--output <FORMAT>`	-	Output format: `table` or `json`	`table`
`-v`, `--verbose`	-	Increase verbosity level (repeatable: `-v`, `-vv`, `-vvv`)	-
`-q`, `--quiet`	-	Quiet mode (errors only)	-

Verbosity Levels

Flag	Level	Use Case
(default)	WARN	Normal operation
`-v`	INFO	General information
`-vv`	DEBUG	Troubleshooting
`-vvv`	TRACE	Deep debugging
`-q`	ERROR	Scripts (errors only)

JSON output

--output json makes a command print exactly one JSON document on stdout, in the same envelope the REST API uses. Success wraps the payload under data:

{
  "data": {
    "strategyId": "a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d",
    "name": "momentum-v1"
  }
}

List commands (strategy list, version list, scenario list, config list) put the array under that same data key, with nextCursor beside it when another page exists. A failed command replaces data with error:

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "API key not found. Set TEKTII_API_KEY environment variable or use --api-key"
  }
}

The error document goes to stdout, not stderr — so one | jq sees both outcomes. Logs, progress spinners, and table mode's human-readable chatter all go to stderr or are suppressed, leaving stdout parseable.

The code values here are the CLI's own (AUTH_REQUIRED, AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, CLIENT_ERROR, INTERNAL_ERROR) — they classify local failures too, so do not expect them to match the REST error codes one for one.

Exit codes

Exit code	When	stdout
`0`	The command succeeded	`{ "data": ... }`
`1`	The command ran and failed — auth, validation, not found, API or network error	`{ "error": ... }`
`2`	Usage error — unknown command, unrecognized flag, missing argument. The argument parser rejects the invocation before the command runs	(empty — the message is plain text on stderr)

The exit code is reliable: branch on it rather than inspecting which key came back. 0 always pairs with a data document and 1 always pairs with an error document, so if tektii ... ; then is enough for the success/failure split, and you only need to parse stdout when you want the payload or the error code.

The case to guard is 2: nothing is written to stdout, so a script that pipes unconditionally into a JSON parser fails there with a confusing parse error rather than the real message.

if out=$(tektii scenario get "$STRATEGY_ID" "$SCENARIO_ID" --output json); then
  echo "$out" | jq -r '.data.state'
else
  # exit 2 leaves $out empty — fall back to the plain-text message on stderr
  echo "$out" | jq -r '.error.message // "usage error"' >&2
  exit 1
fi

Confirming deletes

strategy delete and config delete ask for confirmation on stdin before they destroy anything. Under --output json there is no prompt to answer, so rather than delete unconfirmed they refuse to run without -y, --yes and exit 1, with this message in the error document:

strategy delete requires --yes in --output json mode (no interactive prompt available)

config delete fails the same way, with its own name in the message. Pass --yes from scripts — it is the only way either command deletes anything in JSON mode.

scenario download is the exception

scenario download without --file prints the requested result payload itself — metadata, timeseries, or trades. That is file content rather than an API resource, so it is not wrapped in a data envelope. Pass --file and stdout gets the usual envelope instead: {"data": {"savedTo": "...", "bytes": 12345, "resultType": "trades"}}.

strategy

Manage trading strategies.

strategy init

Start Here

strategy init is the recommended starting point for new users. It scaffolds a working example strategy on your machine and requires no API key — it is pure local scaffolding, unlike every other command, which talks to the API.

Scaffold a starter strategy directory from a template. Templates are fetched from the Tektii trading-gateway examples.

tektii strategy init [<TEMPLATE>] [<DIR>] [--force]

Argument	Required	Default	Description
`<TEMPLATE>`	No	-	Template to scaffold. Omit to list the available templates.
`<DIR>`	No	`./<TEMPLATE>/`	Target directory for the scaffolded files; defaults to `./<TEMPLATE>/`.
`--force`	No	-	Overwrite files when the target directory is not empty.

Available templates: ma-crossover, rsi-momentum. The catalog is fetched live from GitHub, so run the command with no arguments to see the current list:

# List the available templates
tektii strategy init

Examples:

# Scaffold the moving-average crossover example into ./ma-crossover/
tektii strategy init ma-crossover

# Scaffold into a custom directory
tektii strategy init ma-crossover my-bot

# Overwrite an existing, non-empty directory
tektii strategy init rsi-momentum my-bot --force

After scaffolding, a typical first run is:

cd ma-crossover
uv sync --all-extras                            # install dependencies
uv run pytest                                   # run the example test
tektii strategy create --name "ma-crossover"    # register it, note the strategy ID
tektii version upload <STRATEGY_ID>             # ship it

strategy create

Create a new trading strategy.

tektii strategy create --name <NAME>

Argument	Required	Description
`-n`, `--name <NAME>`	Yes	Strategy name

Example:

tektii strategy create --name "momentum-v1"

strategy list

List all strategies with pagination support.

tektii strategy list [--limit <N>] [--cursor <CURSOR>]

Argument	Required	Default	Description
`-l`, `--limit <N>`	No	20	Number of items to return
`-c`, `--cursor <CURSOR>`	No	-	Pagination cursor for next page

Example:

tektii strategy list --limit 10

strategy get

Get details for a specific strategy.

tektii strategy get <STRATEGY_ID>

Argument	Required	Description
`<STRATEGY_ID>`	Yes	Strategy ID

Example:

tektii strategy get a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d

strategy delete

Delete a strategy and all its versions.

tektii strategy delete <STRATEGY_ID> [--yes]

Argument	Required	Description
`<STRATEGY_ID>`	Yes	Strategy ID
`-y`, `--yes`	Conditional	Skip the confirmation prompt. Required with `--output json` — without it the command fails instead of deleting (see Confirming deletes).

Warning

This permanently deletes the strategy and all its versions, scenarios, and configurations.

Example:

tektii strategy delete a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --yes

strategy set-auto-run

Set the list of scenario configurations that run automatically when a new version is uploaded for this strategy.

tektii strategy set-auto-run <STRATEGY_ID> --configs <CONFIG_IDS>

Argument	Required	Description
`<STRATEGY_ID>`	Yes	Strategy ID
`--configs <CONFIG_IDS>`	Yes	Comma-separated configuration IDs. Pass an empty string to clear.

Examples:

# Run two configs on every new version
tektii strategy set-auto-run a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d \
  --configs d4e5f6a7-b8c9-4d4e-8f5a-6b7c8d9e0f1a,f1a2b3c4-d5e6-4f1a-8b2c-3d4e5f6a7b8c

# Clear the auto-run list
tektii strategy set-auto-run a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --configs ""

version

Manage strategy versions.

version upload

Create a new strategy version — either by building and pushing a Docker image, or from a platform template that skips Docker entirely.

tektii version upload <STRATEGY_ID> \
  [--git-sha <SHA>] \
  [--dockerfile <PATH>] \
  [--context <PATH>] \
  [--parent <VERSION_ID>] \
  [--template <TEMPLATE>]

Argument	Required	Default	Description
`<STRATEGY_ID>`	Yes	-	Strategy ID
`--git-sha <SHA>`	No	Auto-detected	Git commit SHA
`--dockerfile <PATH>`	No	`./Dockerfile`	Path to Dockerfile (ignored when `--template` is used)
`--context <PATH>`	No	`.`	Docker build context directory (ignored when `--template` is used)
`--parent <VERSION_ID>`	No	-	Parent version ID when branching from an existing version
`--template <TEMPLATE>`	No	-	Create the version from a platform template instead of building a Docker image. Available templates: `ma-crossover`, `rsi-momentum`.

Process (Docker build):

Validates Dockerfile exists
Auto-detects git SHA (or uses timestamp fallback)
Creates version entry in API
Builds Docker image for linux/amd64 platform
Pushes image to registry

Process (--template):

Skips Dockerfile validation, Docker build, and registry push
Creates version entry in API and the server copies the template image into your strategy
Useful for first-run users who want a working strategy without configuring Docker

Examples:

# From strategy repository root
cd /path/to/my-strategy
tektii version upload a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d

# With custom paths
tektii version upload a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d \
  --dockerfile ./docker/Dockerfile.prod \
  --context ./src

# Use a platform template (no Docker needed)
tektii version upload a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --template ma-crossover

# Branch from an existing version
tektii version upload a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --parent b2c3d4e5-f6a7-4b2c-8d3e-4f5a6b7c8d9e

--git-sha records traceability and --parent records lineage — see Version provenance & branching in the Write Workflow.

version list

List versions for a strategy.

tektii version list <STRATEGY_ID> [--limit <N>] [--cursor <CURSOR>]

Argument	Required	Default	Description
`<STRATEGY_ID>`	Yes	-	Strategy ID
`-l`, `--limit <N>`	No	20	Number of items to return
`-c`, `--cursor <CURSOR>`	No	-	Pagination cursor

Example:

tektii version list a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d

version get

Get details for a specific version.

tektii version get <STRATEGY_ID> <VERSION_ID>

Argument	Required	Description
`<STRATEGY_ID>`	Yes	Strategy ID
`<VERSION_ID>`	Yes	Version ID

Example:

tektii version get a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d b2c3d4e5-f6a7-4b2c-8d3e-4f5a6b7c8d9e

scenario

Manage backtest scenarios.

Check the data catalog before authoring a scenario

A scenario configuration references instrument symbols and a date window. Use Available Instruments to see which symbols exist and how far back data goes, then keep your window inside each instrument's dataStartDate → dataEndDate range. Your plan also caps how far back a run can reach and how long a single run can span — see Plan Limits before sizing a long window.

scenario run

Launch a backtest. This is the only command that starts a run — it returns a scenario id at QUEUED, which you then inspect with scenario get and scenario download.

Every run needs a strategy, a version, and a config. The strategy is always --strategy-id; where the version and config come from depends on which of the two mutually exclusive sources you pick:

Source	Config comes from	Version comes from
`--file <FILE>`	A one-shot JSON config file, not saved to your account	The file's own `strategyVersionId` field
`--config <CONFIG_ID>`	A configuration previously saved with `config create`	`--version-id`, which is required here

Exactly one of --file / --config must be supplied — passing both, or neither, is an error.

tektii scenario run --strategy-id <STRATEGY_ID> --file <FILE>
tektii scenario run --strategy-id <STRATEGY_ID> --config <CONFIG_ID> --version-id <VERSION_ID>

Argument	Required	Description
`--strategy-id <STRATEGY_ID>`	Yes	Strategy to run against
`--file <FILE>`	One of	Path to a one-shot JSON config file. Supplies its own `strategyVersionId`. Mutually exclusive with `--config`
`--config <CONFIG_ID>`	One of	Saved configuration id to run. Mutually exclusive with `--file`
`--version-id <VERSION_ID>`	Conditional	Strategy version to run. Required with `--config`, since a saved config doesn't pin a version. With `--file` the version comes from the file, so this flag is not accepted there
`--env <KEY=VAL>`	No	Per-run env override, repeatable. Layered over the config's `env` — the flag wins on a duplicate key. Plain text; not for secrets
`--env-file <PATH>`	No	Read env overrides from a file (`KEY=VAL` per line; blank lines and `#` comments ignored). An inline `--env` wins on a duplicate key

See Scenario Configuration for the config-file schema, including per-instrument events and a custom start time that the web wizard does not author.

Example — one-shot config file:

tektii scenario run \
  --strategy-id a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d \
  --file ./backtest-config.json

Example — saved configuration:

tektii scenario run \
  --strategy-id a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d \
  --config d4e5f6a7-b8c9-4d4e-8f5a-6b7c8d9e0f1a \
  --version-id b2c3d4e5-f6a7-4b2c-8d3e-4f5a6b7c8d9e

Example — overriding strategy parameters for one run:

tektii scenario run \
  --strategy-id a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d \
  --config d4e5f6a7-b8c9-4d4e-8f5a-6b7c8d9e0f1a \
  --version-id b2c3d4e5-f6a7-4b2c-8d3e-4f5a6b7c8d9e \
  --env MA_SHORT=20 --env MA_LONG=50

Identical re-runs are deduplicated

Backtests are deterministic, so re-launching an identical (version, config) pair that already ran successfully links to the prior run instead of starting a new one. Change the version, the config, or an env override to force a fresh run.

scenario list

List scenarios for a strategy.

tektii scenario list <STRATEGY_ID> [--limit <N>] [--cursor <CURSOR>]

Argument	Required	Default	Description
`<STRATEGY_ID>`	Yes	-	Strategy ID
`-l`, `--limit <N>`	No	20	Number of items to return
`-c`, `--cursor <CURSOR>`	No	-	Pagination cursor

Example:

tektii scenario list a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d

scenario get

Get details for a specific scenario.

tektii scenario get <STRATEGY_ID> <SCENARIO_ID>

Argument	Required	Description
`<STRATEGY_ID>`	Yes	Strategy ID
`<SCENARIO_ID>`	Yes	Scenario ID

Example:

tektii scenario get a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f

scenario download

Download backtest results (metadata, timeseries, or trades).

tektii scenario download <STRATEGY_ID> <SCENARIO_ID> [options]

Argument	Required	Default	Description
`<STRATEGY_ID>`	Yes	-	Strategy ID
`<SCENARIO_ID>`	Yes	-	Scenario ID
`-f`, `--file <PATH>`	No*	-	Output file path
`--result-type <TYPE>`	No	`metadata`	Type: `metadata`, `timeseries`, or `trades`
`--format <FORMAT>`	No	`table`	Display format (terminal only)
`--raw`	No	-	Output raw zstd-compressed data (requires `--file`; binary cannot be written to the terminal)

*Required for timeseries and trades result types.

Examples:

# View metadata in terminal
tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f

# Save metadata to a file (always written as JSON)
tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --file metadata.json

# Download full timeseries
tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --result-type timeseries \
  --file timeseries.json

# Download trade log
tektii scenario download a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f \
  --result-type trades \
  --file trades.json

scenario cancel

Stop a backtest before it finishes. Works while the run is QUEUED, PENDING, or RUNNING; the scenario moves to CANCELLED and produces no results.

tektii scenario cancel <STRATEGY_ID> <SCENARIO_ID>

Argument	Required	Description
`<STRATEGY_ID>`	Yes	Strategy ID
`<SCENARIO_ID>`	Yes	Scenario ID

Example:

tektii scenario cancel a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d c3d4e5f6-a7b8-4c3d-9e4f-5a6b7c8d9e0f

A run that already reached COMPLETE, FAILED, or CANCELLED has nothing left to stop — the API rejects the request with 400 and the CLI prints the reason.

Scenario states

Every scenario reports a state. scenario get returns the current one. There are six:

State	Terminal?	Meaning
`QUEUED`	No	Accepted and enqueued, awaiting dispatch. `scenario run` returns this — submission is asynchronous, so a fresh run starts here.
`PENDING`	No	Dispatched — the backtest container is starting up.
`RUNNING`	No	The backtest is executing.
`COMPLETE`	Yes	Finished successfully — results are available via `scenario get` / `scenario download`.
`FAILED`	Yes	The run stopped on an error. Inspect the scenario's error fields for the cause; no results.
`CANCELLED`	Yes	Stopped on request from `QUEUED`, `PENDING`, or `RUNNING` — see cancelling a run below. No results.

The happy path is QUEUED → PENDING → RUNNING → COMPLETE. FAILED and CANCELLED are the two terminal alternatives — a run reaches exactly one of COMPLETE / FAILED / CANCELLED and then stops changing.

Cancelling a run. Every surface can cancel a QUEUED, PENDING, or RUNNING scenario:

Surface	How
CLI	`scenario cancel <STRATEGY_ID> <SCENARIO_ID>`
Web app	The Cancel button on an in-flight scenario
MCP	The `cancel_scenario` tool
REST	`POST /v1/strategies/{strategy_id}/scenarios/{scenario_id}/cancel` — see the API reference

All four hit the same endpoint, so they behave identically: the scenario ends at CANCELLED with no results, and a request against an already-terminal run is rejected with 400.

Submission is asynchronous

Submitting a run (scenario run, or the MCP run_scenario / batch_run_scenarios tools) enqueues it and returns immediately with state: QUEUED; the run moves to PENDING once it is dispatched. Poll to a terminal state rather than assuming any particular initial value.

The success state is COMPLETE, not COMPLETED

The terminal success state is spelled COMPLETE. A poll loop that waits for COMPLETED never matches — it spins forever with no error, because the state simply never takes that value. Poll until state is one of COMPLETE, FAILED, or CANCELLED.

config

Manage reusable scenario configurations.

config create

Create a reusable scenario configuration.

tektii config create --file <FILE> [--name <NAME>]

Argument	Required	Description
`-n`, `--name <NAME>`	No	Configuration name. Authoritative when passed — it overrides any `name` in the file. Omit it and the file must carry its own `name`
`-f`, `--file <FILE>`	Yes	Path to a JSON configuration file in the saved-config schema
`--env <KEY=VAL>`	No	Default env override stored on the preset, repeatable. Layered over the file's `env` block — the flag wins on a duplicate key. Plain text; not for secrets
`--env-file <PATH>`	No	Read default env overrides from a file (`KEY=VAL` per line; blank lines and `#` comments ignored). An inline `--env` wins on a duplicate key

These flags set the configuration's stored default env, not a per-run value: every run of this preset starts from it, and scenario run --env layers on top at launch. See Environment variables for the full precedence chain.

This is not a scenario run --file config

--file here takes the saved-config schema, which has no strategyVersionId — a saved preset does not pin a version, and scenario run --config supplies one with --version-id at launch. Handing an inline scenario run --file config to this command is rejected with an unknown-field error naming strategyVersionId. Delete that key (and add a name, unless you pass --name) to convert one into the other. Full field-by-field difference: The two config schemas.

Example:

tektii config create \
  --name "2023-backtest" \
  --file ./config.json

config list

List your configurations.

tektii config list [--limit <N>] [--cursor <CURSOR>]

Argument	Required	Default	Description
`-l`, `--limit <N>`	No	20	Number of items to return
`-c`, `--cursor <CURSOR>`	No	-	Pagination cursor

Example:

tektii config list

config get

Get details for a specific configuration.

tektii config get <CONFIG_ID>

Argument	Required	Description
`<CONFIG_ID>`	Yes	Configuration ID

Example:

tektii config get d4e5f6a7-b8c9-4d4e-8f5a-6b7c8d9e0f1a

config update

Update an existing configuration.

tektii config update <CONFIG_ID> --file <FILE>

Argument	Required	Description
`<CONFIG_ID>`	Yes	Configuration ID
`-f`, `--file <FILE>`	Yes	Path to an updated JSON configuration, in the same saved-config schema `config create` takes — not an inline `scenario run --file` config

Example:

tektii config update d4e5f6a7-b8c9-4d4e-8f5a-6b7c8d9e0f1a --file ./updated-config.json

config delete

Delete a configuration.

tektii config delete <CONFIG_ID> [--yes]

Argument	Required	Description
`<CONFIG_ID>`	Yes	Configuration ID
`-y`, `--yes`	Conditional	Skip the confirmation prompt. Required with `--output json` — without it the command fails instead of deleting (see Confirming deletes).

Example:

tektii config delete d4e5f6a7-b8c9-4d4e-8f5a-6b7c8d9e0f1a --yes

Running a saved config

The config group manages presets only — it has no run verb. To launch a saved configuration, use scenario run --config <CONFIG_ID>.

Next Steps

Authentication - Configure your API key
Read Workflow - List strategies and download results
Write Workflow - Push Docker images as versions