CLI reference

Last updated 6 September 2026

Verified against frontier-runner 0.1.1

Every command below was checked against frontier --help and that subcommand's --help. Flags not listed here are not part of this release. ConfigError and InstallError print to stderr and exit 1.

frontier --help
frontier --version

Onboarding commands

Open hosted Frontier signup.

Syntax	`frontier signup [--api-url API_URL]`
Important options	--api-url SaaS origin. Default is the hosted Frontier origin.
Required files or environment	A browser, or the printed URL.
Artifacts written	None. Prints the sign-up URL and tries to open it.
Accesses SaaS	Opens the public sign-up page only.
Accesses Snowflake	No.
Exit behavior	Always 0 after printing the URL.

frontier signup

Store a project API key in the OS keychain.

Syntax	`frontier login --api-key [--api-url API_URL]`
Important options	--api-key is required for this version (hidden prompt). Without it the command tells you browser login is unavailable and exits 1. --api-url SaaS origin.
Required files or environment	A project API key created in Settings after sign-in.
Artifacts written	OS keychain item, or ~/.config/frontier/credentials with mode 0600 if the keychain is unavailable.
Accesses SaaS	Yes. Validates the key with GET /api/v1/auth/whoami.
Accesses Snowflake	No.
Exit behavior	0 when stored. 1 if --api-key is omitted. AUTH_CANCELLED / AUTH_INVALID exit 1.

frontier login --api-key

logout

Remove stored Frontier API credentials.

Syntax	`frontier logout`
Important options	None.
Required files or environment	None.
Artifacts written	Deletes keychain and fallback credential files.
Accesses SaaS	No.
Accesses Snowflake	No.
Exit behavior	0.

frontier logout

auth status

Show whether the CLI is authenticated.

Syntax	`frontier auth status`
Important options	None. There is no other auth subcommand.
Required files or environment	Stored credentials, FRONTIER_API_KEY, or the 0600 fallback file.
Artifacts written	None.
Accesses SaaS	Yes, when credentials are present (whoami).
Accesses Snowflake	No.
Exit behavior	0 if Frontier accepts the key. 1 if not authenticated or the key is rejected.

frontier auth status

init

Detect the dbt project and write .frontier/config.yml.

Syntax	`frontier init [project_dir] [--project-dir DIR] [--force] [--yes] [--legacy-yml] [--config CONFIG]`
Important options	--force overwrite. --yes accept detected defaults. --legacy-yml writes example frontier.yml instead of .frontier/config.yml. --config is unused unless --legacy-yml is set.
Required files or environment	dbt_project.yml in the project directory.
Artifacts written	.frontier/config.yml and gitignore entries for Frontier cache/credentials.
Accesses SaaS	No.
Accesses Snowflake	No. Reads local dbt/git detection only.
Exit behavior	0. DBT_PROJECT_MISSING exits 1.

frontier init --yes

discover

Infer a draft semantic manifest from dbt artifacts.

Syntax	`frontier discover [project_dir] [--yes] [--model MODEL]`
Important options	--yes select the first suggested model. --model target model name.
Required files or environment	target/manifest.json or a working dbt compile. Stored API credentials.
Artifacts written	None locally. Uploads a draft to SaaS.
Accesses SaaS	Yes. POST draft manifest. Never activates.
Accesses Snowflake	No.
Exit behavior	0 when a draft version is created. DISCOVER_* / AUTH_* / DBT_ARTIFACT_MISSING exit 1.

frontier discover --yes

doctor

Diagnose the local Frontier installation.

Syntax	`frontier doctor [project_dir] [--json] [--skip-warehouse]`
Important options	--json redacted JSON for support. --skip-warehouse skip the live Snowflake ping.
Required files or environment	A dbt project directory. Optional stored credentials for SaaS checks.
Artifacts written	None.
Accesses SaaS	Yes, reachability/auth/manifest checks when credentials exist.
Accesses Snowflake	Yes, unless --skip-warehouse.
Exit behavior	0 if all checks pass. 1 if any check failed.

frontier doctor --skip-warehouse

update-check

Compare this runner to the hosted latest.

Syntax	`frontier update-check [project_dir] [--api-url API_URL]`
Important options	--api-url SaaS origin.
Required files or environment	Network access to SaaS. Does not auto-update.
Artifacts written	A daily cache file under ~/.cache/frontier/update-check.
Accesses SaaS	Yes. GET /api/v1/runner/versions.
Accesses Snowflake	No.
Exit behavior	0 when the installed version meets the minimum. RUNNER_UNSUPPORTED exits 1.

frontier update-check

Setup commands

setup github

Write .github/workflows/frontier.yml.

Syntax	`frontier setup github [project_dir] [--force] [--yes] [--blocking]`
Important options	--force overwrite. --yes accept defaults. --blocking set FRONTIER_BLOCKING=true (default false for the first PR).
Required files or environment	A GitHub origin. Optional gh CLI to write secrets.
Artifacts written	.github/workflows/frontier.yml. May generate FRONTIER_ENTITY_HASH_KEY.
Accesses SaaS	No, unless you already stored an API key that gh copies into secrets.
Accesses Snowflake	No. Prints a reminder to set Snowflake secrets without printing values.
Exit behavior	0. GITHUB_REMOTE_MISSING / GITHUB_WORKFLOW_* / GITHUB_SECRET_MISSING exit 1.

frontier setup github --yes

setup hash-key

Generate FRONTIER_ENTITY_HASH_KEY.

Syntax	`frontier setup hash-key [--yes] [--copy] [--print-key]`
Important options	--yes store with gh when available. --copy copy the complete key to the clipboard. --print-key print the complete key.
Required files or environment	Optional gh CLI. The hash key is not sent to SaaS.
Artifacts written	None locally unless you print/copy/store it.
Accesses SaaS	No.
Accesses Snowflake	No.
Exit behavior	0. CLIPBOARD_UNAVAILABLE exits 1 if --copy cannot find pbcopy/xclip/wl-copy.

frontier setup hash-key --yes

setup snowflake

Print least-privilege Snowflake grants.

Syntax	`frontier setup snowflake [project_dir] [--cdc] [--query-history]`
Important options	--cdc include CDC stream grants. --query-history include imported Snowflake query-history privileges.
Required files or environment	Optional dbt profile to personalize database/schema names.
Artifacts written	Prints SQL to stdout. Does not execute it.
Accesses SaaS	No.
Accesses Snowflake	No network call. Prints GRANT SQL only.
Exit behavior	0.

frontier setup snowflake --cdc

demo change

Explain a harmless first test PR.

Syntax	`frontier demo change [project_dir]`
Important options	None besides the project directory.
Required files or environment	A dbt project. Frontier will not commit or push.
Artifacts written	None.
Accesses SaaS	No.
Accesses Snowflake	No.
Exit behavior	0.

frontier demo change

SQL-change assessment commands

manifest fetch

Download the active semantic manifest.

Syntax	`frontier manifest fetch [project_dir] [--config CONFIG] [--api-url API_URL] [--output OUTPUT]`
Important options	--output default target/frontier-manifest.json. --config path to frontier.yml. --api-url SaaS origin.
Required files or environment	Stored API credentials and an active SaaS manifest.
Artifacts written	Pinned JSON at --output.
Accesses SaaS	Yes.
Accesses Snowflake	No.
Exit behavior	0. ManifestError codes exit 1.

frontier manifest fetch --output target/frontier-manifest.json

inspect

Read dbt artifacts and print model lineage.

Syntax	`frontier inspect [project_dir] [--config CONFIG] [--manifest-file FILE] [--allow-local-manifest] [--base-manifest FILE]`
Important options	--base-manifest optional base-branch manifest.json. --manifest-file skips the active SaaS fetch. --allow-local-manifest uses frontier.yml mapping when no SaaS manifest is configured.
Required files or environment	target/manifest.json. In GitHub Actions, target/frontier-artifact-sha must match GITHUB_SHA.
Artifacts written	None (prints a report).
Accesses SaaS	Yes unless --manifest-file is set.
Accesses Snowflake	No.
Exit behavior	0, or 1 on ConfigError/ManifestError.

frontier inspect --manifest-file target/frontier-manifest.json --base-manifest target-base/manifest.json

compare

Compare compiled SQL between base-branch and PR manifests.

Syntax	`frontier compare [project_dir] --base-manifest FILE [--pr-manifest FILE] [--output OUTPUT] [--manifest-file FILE] [--allow-local-manifest] [--config CONFIG]`
Important options	--base-manifest is required. --pr-manifest defaults to target/manifest.json. --output writes frontier-compare.json.
Required files or environment	Base and PR manifest.json plus compiled SQL trees when present.
Artifacts written	frontier-compare.json when --output is set; otherwise prints the report.
Accesses SaaS	Yes unless --manifest-file is set.
Accesses Snowflake	No.
Exit behavior	0, or 1 on compare/config errors.

frontier compare --manifest-file target/frontier-manifest.json --base-manifest target-base/manifest.json

run

Execute frontier and validation queries.

Syntax	`frontier run [project_dir] [--profiles FILE] [--target NAME] [--events FILE] [--output FILE] [--run-id ID] [--include-entity-ids] [--hash-entity-ids] [--dry-run] [--base-manifest FILE] [--manifest-file FILE] [--allow-local-manifest] [--config CONFIG]`
Important options	--dry-run uses recorded fixture counts without a live warehouse (forbidden as customer CI). --events defaults to seeds/change_events.csv unless a SQL change is present. --include-entity-ids uploads raw IDs (skips FRONTIER_ENTITY_HASH_KEY). --hash-entity-ids HMAC even when include is set.
Required files or environment	Current dbt artifacts. Live Snowflake unless --dry-run. Hash key unless --include-entity-ids.
Artifacts written	target/frontier-run.json by default.
Accesses SaaS	Fetches the active manifest unless --manifest-file is set. Does not upload.
Accesses Snowflake	Yes, unless --dry-run.
Exit behavior	0, or 1 on warehouse/config errors. Not a substitute for prove.

frontier run --target ci --manifest-file target/frontier-manifest.json --base-manifest target-base/manifest.json

prove

Apply isolated mutations and prove targeted repair equals the full rebuild.

Syntax	`frontier prove [project_dir] [--profiles FILE] [--target NAME] [--events FILE] [--output FILE] [--run-id ID] [--include-entity-ids] [--hash-entity-ids] [--dry-run] [--base-manifest FILE] [--manifest-file FILE] [--allow-local-manifest] [--config CONFIG]`
Important options	Same option names as run. Customer CI must not set FRONTIER_DRY_RUN; prove refuses dry-run when GITHUB_ACTIONS=true.
Required files or environment	Current dbt artifacts, pinned/active semantic manifest, Snowflake (unless dry-run). Hash key unless --include-entity-ids.
Artifacts written	target/frontier-run.json.
Accesses SaaS	Fetches the active manifest unless --manifest-file is set. Does not upload.
Accesses Snowflake	Yes, unless --dry-run.
Exit behavior	0 writes the assessment file even when full rebuild is required. Warehouse/config errors exit 1.

frontier prove --target ci --manifest-file target/frontier-manifest.json --base-manifest target-base/manifest.json

record-failure

Write a failed assessment without reading dbt artifacts.

Syntax	`frontier record-failure [project_dir] [--reason TEXT] [--output FILE] [--run-id ID] [--include-entity-ids] [--hash-entity-ids] [--manifest-file FILE] [--allow-local-manifest] [--config CONFIG]`
Important options	--reason default is 'dbt build failed; no current artifacts'.
Required files or environment	Optional pinned manifest. Does not require target/manifest.json.
Artifacts written	target/frontier-run.json.
Accesses SaaS	Fetches the active manifest unless --manifest-file is set.
Accesses Snowflake	No.
Exit behavior	0.

frontier record-failure --manifest-file target/frontier-manifest.json --reason "base-branch dbt compile failed"

upload

POST aggregate results to Frontier SaaS.

Syntax	`frontier upload [project_dir] [--run-file FILE] [--run-id ID] [--api-url URL] [--blocking] [--skip-pr-comment] [--config CONFIG]`
Important options	--blocking exit 1 after a successful upload when assessment status is failed. --skip-pr-comment do not post or update a GitHub PR comment. --run-file path to frontier-run.json.
Required files or environment	target/frontier-run.json (or --run-file). API credentials. In GitHub Actions, GITHUB_TOKEN is used locally for the comment step only.
Artifacts written	None locally. Creates/updates the dashboard run.
Accesses SaaS	Yes. POST ingest. Snowflake credentials are not in this step's environment in the generated workflow.
Accesses Snowflake	No.
Exit behavior	0 on successful upload unless --blocking and status=failed, then 1. HTTP 429/5xx retries; 413 and other errors exit 1.

frontier upload --blocking

CDC commands

All CDC commands take an optional project directory, --cdc-config (default frontier-cdc.yml), and --config (frontier.yml). Prove/upload also accept --manifest-file and --allow-local-manifest.

cdc inspect

Print configured CDC streams without consuming them.

Syntax	`frontier cdc inspect [project_dir] [--cdc-config FILE] [--config FILE] [--target NAME] [--manifest-file FILE] [--allow-local-manifest]`
Important options	Does not read stream contents.
Required files or environment	frontier-cdc.yml with provider snowflake_stream.
Artifacts written	None.
Accesses SaaS	Yes unless --manifest-file is set (overlay routes from the pinned manifest).
Accesses Snowflake	No.
Exit behavior	0, or 1 if the CDC config is invalid.

frontier cdc inspect

cdc status

Report whether configured streams have pending data.

Syntax	`frontier cdc status [project_dir] [--cdc-config FILE] [--profiles FILE] [--target NAME] [--config FILE]`
Important options	--profiles dbt profiles.yml (default ~/.dbt/profiles.yml). --target dbt target name.
Required files or environment	frontier-cdc.yml and Snowflake connectivity.
Artifacts written	None. Prints STREAM: pending\|empty.
Accesses SaaS	No.
Accesses Snowflake	Yes. Does not consume.
Exit behavior	0.

frontier cdc status

cdc consume

Durably capture pending stream records.

Syntax	`frontier cdc consume [project_dir] [--cdc-config FILE] [--profiles FILE] [--target NAME] [--config FILE]`
Important options	Same warehouse flags as status.
Required files or environment	Snowflake. Control tables in the stream database/schema.
Artifacts written	Durable CDC batch rows in Snowflake. Status EMPTY, REUSED, or a new CAPTURED batch id.
Accesses SaaS	No.
Accesses Snowflake	Yes.
Exit behavior	0 on empty/reuse/capture. 1 if the stream is claimed or capture DML fails.

frontier cdc consume

cdc prove

Route a captured CDC batch and run targeted proof.

Syntax	`frontier cdc prove [project_dir] [--batch-id ID] [--apply] [--profiles FILE] [--target NAME] [--cdc-config FILE] [--manifest-file FILE] [--allow-local-manifest] [--config FILE]`
Important options	--batch-id default oldest CAPTURED or FAILED. --apply apply the repair to the target mart (default assessment only).
Required files or environment	target/manifest.json, pinned/active semantic manifest, captured batch, Snowflake.
Artifacts written	target/frontier-run.json for the CDC assessment.
Accesses SaaS	Fetches the active manifest unless --manifest-file is set.
Accesses Snowflake	Yes.
Exit behavior	0 when proof completes. 1 if the batch is missing, already proved, or SQL cannot be filtered safely.

frontier cdc prove

cdc upload

Upload a completed CDC assessment to Frontier SaaS without re-running proof.

Syntax	`frontier cdc upload [project_dir] [--batch-id ID] [--api-url URL] [--profiles FILE] [--target NAME] [--cdc-config FILE] [--manifest-file FILE] [--allow-local-manifest] [--config FILE]`
Important options	--batch-id default newest COMPLETED batch not yet uploaded.
Required files or environment	Completed proof evidence and API credentials. Snowflake is used to read control-table state and mart row counts, not to send rows to SaaS.
Artifacts written	Marks the batch uploaded in Snowflake control tables.
Accesses SaaS	Yes.
Accesses Snowflake	Yes, for batch metadata and mart counts. Upload payload is aggregates only.
Exit behavior	0. BASELINE_STALE, missing batch, or failed validation exit 1.

frontier cdc upload