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 that config against a strategy version, and creating one launches a backtest (it returns a scenario id at QUEUED). So config create saves a preset for later, while scenario create and scenario run start a run.

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)

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`	No	Skip confirmation prompt

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 create

Create a new backtest scenario from a JSON configuration file. See Scenario Configuration for the config-file schema, including per-instrument events and a custom start time that the web wizard does not author.

tektii scenario create <STRATEGY_ID> --config <FILE>

Argument	Required	Description
`<STRATEGY_ID>`	Yes	Strategy ID
`-c`, `--config <FILE>`	Yes	Path to JSON configuration file

Example:

tektii scenario create a1b2c3d4-e5f6-4a1b-9c2d-3e4f5a6b7c8d --config ./backtest-config.json

scenario run

Alias of config run — runs a saved configuration as a backtest against a strategy version, so the subscriptions, window, and capital don't need to be re-supplied inline.

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

Argument	Required	Description
`<CONFIG_ID>`	Yes	Saved configuration ID to run
`--strategy-id <STRATEGY_ID>`	Yes	Strategy to run the configuration against
`--version-id <VERSION_ID>`	Yes	Strategy version to run

Example:

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

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 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 create` / `scenario run` return 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	Cancelled before completion. 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. A scenario cancel works from QUEUED, PENDING, or RUNNING.

Submission is asynchronous

Submitting a run (scenario create / 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 --name <NAME> --file <FILE>

Argument	Required	Description
`-n`, `--name <NAME>`	Yes	Configuration name
`-f`, `--file <FILE>`	Yes	Path to JSON configuration file

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 updated JSON configuration

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`	No	Skip confirmation prompt

Example:

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

config run

Run a saved configuration as a backtest against a strategy version. Identical to scenario run — same arguments, same behaviour; the scenario run form just lives under the scenario group so it's discoverable from tektii scenario --help. Use whichever you remember.

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

Argument	Required	Description
`<CONFIG_ID>`	Yes	Saved configuration ID to run
`--strategy-id <STRATEGY_ID>`	Yes	Strategy to run the configuration against
`--version-id <VERSION_ID>`	Yes	Strategy version to run

Example:

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

Next Steps

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