CLI Reference
Reference for the thyme command-line interface.
The thyme CLI is the primary way to commit feature definitions, inspect platform state, and query features from the terminal.
Commands at a glance:
| Command | Purpose |
|---|---|
version | Print the installed SDK version |
commit | Send feature definitions to the control plane |
status | Show system status (services, definitions, jobs) |
logs | Tail service events |
discover | LLM-powered feature discovery from a source |
login / logout | Store / clear credentials |
query | Online feature query (single or batch) |
query-offline | Historical / batch feature query with timestamps |
lookup | Raw dataset point lookup |
inspect | System metadata or single-featureset detail |
codegen python | Generate .pyi stubs for typed feature queries |
After every query command, Thyme prints a Query run: <id> footer. When the frontend URL is configured (see Configuration), a Results: <url> line is also printed, linking directly to the run in the web UI where you can see metadata and replay the query.
thyme version
Prints the installed Thyme SDK version.
thyme version
# thyme 0.1.0thyme commit
Imports a feature module, serializes all registered definitions, and sends them to the Thyme control plane.
thyme commit [OPTIONS] [PATH]| Option | Short | Env var | Default | Description |
|---|---|---|---|---|
PATH (positional) | - | - | - | Python file with feature definitions |
--module MODULE | -m | - | - | Import by dotted module path instead |
--dry-run | - | - | False | Print the payload instead of POSTing |
--output FILE | - | - | - | Write dry-run payload to a file |
--api-url URL | - | THYME_API_URL | from thyme login | Thyme instance URL |
thyme commit features.py
thyme commit -m myproject.features
thyme commit features.py --dry-run --output payload.jsonthyme status
Shows service health, committed definitions, and recent jobs.
thyme status [--json] [--api-url URL] [--query-url URL]Pass --json to emit a machine-readable blob (useful in scripts).
thyme logs
Tails recent service events from the definition-service. Useful for watching a fresh commit land.
thyme logs [--limit N] [--severity warn|error|info] [--event-type TYPE]thyme discover
LLM-powered feature discovery. Point it at a data source and it drafts a Thyme feature module.
thyme discover --source iceberg --table sales.orders --use-case fraudSee thyme discover --help for the full option set.
thyme login / thyme logout
Store and clear credentials at ~/.thyme/credentials:
thyme login --api-key <token> --api-base https://thyme.internal
thyme logoutthyme query
Online feature query. Auto-routes to a single GET when one --entity is supplied, or a batch POST when multiple are.
thyme query FEATURESET_REF [OPTIONS]FEATURESET_REF uses the module:ClassName form (e.g. myproject.features:UserFeatures).
| Option | Short | Env var | Default | Description |
|---|---|---|---|---|
--entity VALUE | -e | - | - | Entity ID (repeatable; supports @file.txt and comma splits) |
--module PATH | -m | - | - | Import module from a file path instead of a dotted name |
--format FMT | -f | - | table | table, json, csv, parquet, arrow |
--output PATH | -o | - | - | Output file (required for parquet/arrow) |
--limit N | - | - | 50 | Truncation for table display |
--query-url URL | - | THYME_QUERY_URL | from thyme login | Query-server URL |
--api-key KEY | - | THYME_API_KEY | - | Bearer token |
thyme query myproject.features:UserFeatures -e user_42
thyme query myproject.features:UserFeatures -e user_1 -e user_2 -e user_3
thyme query myproject.features:UserFeatures -e @ids.txt --format parquet -o out.parquetthyme query-offline
Historical / batch feature query with per-row timestamps - the workflow you use to build training data.
thyme query-offline FEATURESET_REF [--input FILE | -e ID --at TS ...] [OPTIONS]Two input modes:
- File (recommended):
--input rows.{parquet,csv,jsonl}with columnsentity_id+timestamp(configurable via--entity-column/--timestamp-column). - Inline flags: repeated
-e ID --at ISO-8601pairs for ad-hoc runs.
These are mutually exclusive - the CLI errors if both are supplied.
| Option | Default | Description |
|---|---|---|
--input FILE (-i) | - | .parquet, .csv, .tsv, or .jsonl |
--entity VALUE (-e) | - | Ad-hoc entity ID (pairs with --at) |
--at TIMESTAMP | - | ISO-8601 timestamp; 1:1 with -e |
--entity-column NAME | entity_id | Column in --input |
--timestamp-column NAME | timestamp | Column in --input |
--batch-size N | 5000 | Rows per request |
--format FMT (-f) | table | As above |
--output PATH (-o) | - | As above |
thyme query-offline myproject.features:UserFeatures \
--input training_rows.parquet \
--entity-column user_id --timestamp-column event_ts
thyme query-offline myproject.features:UserFeatures \
-e user_1 --at 2026-04-01T00:00:00Z \
-e user_2 --at 2026-04-01T00:00:00Zthyme lookup
Direct dataset point lookup - returns a raw row from the feature store, skipping the extractor pipeline.
thyme lookup DATASET_REF -e ENTITY_ID [--at ISO-8601] [--format table|json]thyme lookup myproject.features:Purchase -e txn_42
thyme lookup myproject.features:Purchase -e txn_42 --at 2026-04-01T00:00:00Zthyme inspect
Prints system metadata (when called without arguments - mirrors thyme status), or detailed metadata for a single featureset.
thyme inspect # system-wide
thyme inspect myproject.features:UserFeatures # one featureset
thyme inspect myproject.features:UserFeatures --json # raw JSONthyme codegen python
Introspects your @featureset and @dataset classes and emits .pyi stub files so type-checkers (mypy, pyright, pylance) can narrow ThymeClient.query / query_batch / query_offline / lookup - and their MockContext counterparts - by featureset. Autocomplete on row attributes, type errors on typos, no guesswork.
thyme codegen python FILE --out DIR [--force]| Argument / Option | Short | Description |
|---|---|---|
FILE | - | Path to the Python file containing feature definitions (positional) |
--out DIR | - | Output directory for generated stubs (created if missing) |
--force | - | Overwrite an existing output directory and prune stale *.pyi files |
--path FILE | - | Alias for the positional FILE argument |
--module MODULE | -m | Deprecated — pass the file path positionally instead |
thyme codegen python features.py --out stubs/
thyme codegen python features.py --out stubs/ --forceOne .pyi is emitted per featureset and per dataset, plus an __init__.pyi that re-exports each row class. Point your type-checker at the output directory (e.g. mypy.ini's mypy_path or pyrightconfig.json's extraPaths), or re-export the stubs from your own package's __init__.pyi.
Runtime behaviour is unchanged. .pyi files are read only by type-checkers - Python does not load them at runtime. The query hot path stays Arrow / Polars throughout, so stub generation adds no latency, no memory footprint, and no dependency surface to the running SDK.
The stubs reflect whatever is registered when the input module is imported. Regenerate after editing featureset / dataset declarations to keep narrowing accurate.
Configuration
Every command reads config in priority order:
- CLI flags (e.g.
--query-url,--api-key) - Environment variables (
THYME_QUERY_URL,THYME_API_KEY,THYME_API_URL,THYME_FRONTEND_URL) .thyme.yamlin the current directory~/.thyme.yaml- Stored credentials from
thyme login(~/.thyme/credentials)
THYME_FRONTEND_URL
Set this to the base URL of your Thyme web UI. When set, query commands print a clickable Results: link to the query-run detail page.
export THYME_FRONTEND_URL=https://thyme.your-company.com
thyme query myproject.features:UserFeatures -e user_42
# ...table...
# Query run: 7b3e4c...
# Results: https://thyme.your-company.com/query-runs/7b3e4c...See Query Runs for what the UI shows.
Error behaviour
On any error - missing entity, auth failure, server down - each command writes a message to stderr and exits with code 1. Success is always exit code 0.