CLI

Installing honeyframeapi also installs the honeyframe command. It reads the same environment variables as HoneyframeClient.from_env() and prints results as JSON (or CSV).

export HONEYFRAME_URL=https://platform.your-domain.com
export HONEYFRAME_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx

honeyframe whoami
honeyframe projects -f csv
honeyframe sql "SELECT COUNT(*) AS n FROM marts.fact_orders" -p 7

Flags go after the subcommand: honeyframe <command> [arguments] [flags].

Common flags

Every command except the plugin commands accepts:

Flag	Meaning
--url URL	Platform base URL. Default: $HONEYFRAME_URL.
--token-file PATH	Read the token (a PAT or session token) from a file.
--token -	Read the token from standard input.
--token VALUE	Pass the token literally. Works, but prints a warning: the value is visible in the process list and shell history.
-o ID, --org ID	Organization id (sent as X-Org-Id).
-p ID, --project ID	Project id (sent as X-Project-Id). Default: $HONEYFRAME_PROJECT_ID.
-f json|csv, --format json|csv	Output format. Default json. CSV applies to row results and lists of records.

--token-file and --token - are 0.1.8+. Without a token flag, the CLI uses HONEYFRAME_TOKEN, then HONEYFRAME_USERNAME with HONEYFRAME_PASSWORD. honeyframe --version prints the installed SDK version.

honeyframe whoami --token-file ~/.config/honeyframe/token
printenv CI_HONEYFRAME_TOKEN | honeyframe projects --token -

Commands

honeyframe whoami

Your user profile.

honeyframe version

The platform's version (not the SDK's; use honeyframe --version for that).

honeyframe projects

The projects you can see.

honeyframe datasets

The datasets in the project given by -p (or HONEYFRAME_PROJECT_ID).

honeyframe sql QUERY

Runs QUERY through the governed SQL endpoint in the -p project and prints the rows. The default row limit (10,000) applies.

honeyframe sql "SELECT store_key, SUM(amount) AS revenue FROM marts.fact_orders GROUP BY 1" -p 7 -f csv > revenue.csv

honeyframe engine

Prints {"engine": "dbt" | "native", "uses_dbt": ...} for the -p project.

honeyframe lineage DATASET [--down]

Upstream lineage of a dataset in the -p project; --down shows the downstream dependents instead.

honeyframe upload NAME FILE [--replace] [--materialize]

Uploads a local .csv or .xlsx file as dataset NAME in the -p project. --replace overwrites an existing upload; --materialize copies it into the warehouse afterwards.

honeyframe export DATASET PATH [--max-rows N]

Exports a dataset to a local file: Parquet when PATH ends in .parquet (needs honeyframeapi[parquet]), CSV otherwise. --max-rows caps the rows pulled.

honeyframe pat create [--name NAME] [--expires-days N]

Mints a Personal Access Token. The JSON on standard output contains the secret, shown once; a reminder to store it goes to standard error, so honeyframe pat create > token.json keeps the reminder visible. Without --expires-days the platform applies its default (90 days); 0 makes a token that never expires.

honeyframe pat list

Your tokens (metadata only).

honeyframe pat revoke ID

Revokes one of your tokens.

honeyframe scenario list

The scenarios of the -p project.

honeyframe scenario run NAME [--wait]

Runs a scenario by name or id in the -p project. --wait blocks until the run reaches a terminal status and prints the final run.

honeyframe plugin

The local plugin kit (0.1.8+). These commands run offline: they take none of the connection flags and need no environment. See Plugins.

Command	Arguments and flags
honeyframe plugin init DIR --type TYPE [--id ID]	TYPE is recipe, transform, connector, scenario_step or monitor_adapter. --id defaults to a sanitized directory name.
honeyframe plugin check DIR	Validates DIR/plugin.json.
honeyframe plugin run DIR COMPONENT [--op OP] [--params FILE] [--input CSV] [--source NAME] [--output CSV] [--pass-env]	OP is process, read, sources, test or run_step (default: inferred from the component type). --params is a JSON file. Runs your code unsandboxed in this process.
honeyframe plugin pack DIR [-o PATH]	Writes the archive to PATH, default <id>-<version>.zip in the current directory. Here -o means --output, not --org.

Exit codes and errors

Code	Meaning
0	Success.
1	A platform or configuration error (any HoneyframeError), a local file error, or a failed plugin command. The message is printed to standard error as error: ….
130	Interrupted with Ctrl-C.
2	Invalid arguments (from the argument parser).

Network failures that persist after the automatic retries (for example, the host cannot be reached) are not converted to an error: line; Python prints the exception and exits with a non-zero status.

---

Verified against honeyframeapi 0.1.8.