Dependencies

The Qyra CLI requires Node, NPM, and the dbt core or dbt cloud CLI to be installed and available under the dbt command.

Known limitations when using dbt cloud CLI

Warehouse credentials dependency for some commands

Affected commands: qyra generate, qyra preview and qyra start-preview

These commands rely on the warehouse credentials from the active project, as the dbt Cloud CLI does not expose credentials directly. Ensure the project's credentials have access to all development and staging schemas for a seamless experience.

Empty warehouse credentials for new projects

Affected commands: qyra deploy --create

When using this command to create a new project that is not a preview, the warehouse credentials will not be populated automatically. Users must update the warehouse credentials manually in the project settings page after the project is created.

Global options

There are three global options that can be used with any Qyra CLI command: version, help, and verbose.

Version

--version or -V

Ignores the preceding command and shows the installed CLI version. Usually it's used right after qyra, like this:

qyra --version

To upgrade, see Updating the Qyra CLI.

Help

--help or -h

Tells you what the preceding command does and lists all command-specific options. You can view the Qyra CLI help like this:

qyra --help

That returns the Qyra CLI help menu:

When you use the --help or -h option with a speific command:

qyra validate -h

That returns details and examples for the command itself:

Verbose

--verbose

Defaults to OFF. When included, each step will print logs as it progresses through the command. For example, here's a --verbose version of qyra generate-exposures:

Commands

The table below includes a complete list of all commands available in the Qyra CLI.

For examples and command-specific options, click through the command in the table for docs, or install the Qyra CLI and use the global help option.

qyra login

Log in to a Qyra instance using email and password or a token.

qyra login [URL]

Argument:

• [URL]
  • The URL for your Qyra instance (see examples below)

Options:

• --token <token>
  • For logging in with an access token (common for SSO users)
  • Exclude this to log in with email and password
• --project <project uuid>
  • Select a project by UUID after login (must be valid UUID)

Examples:

Log in to Qyra Cloud US instance (for most Starter customers):

qyra login https://app.qyraflow.com

Log in to Qyra Cloud EU instance while showing detailed logs of login process:

qyra login https://eu1.qyraflow.com --verbose

Log in to a custom domain with a personal access token (exclude --token to log in with email and password):

qyra login https://custom.qyra.domain --token bv6105f53cb127087189cfib180a3131

qyra connect-snowflake

Sign in to Snowflake using browser-based SSO and deposit a durable credential into an open Qyra project setup wizard. Use this during project creation when your Snowflake account requires SSO or MFA and you want to avoid pasting a password, private key, or PAT.

The CLI opens Snowflake SSO in a browser, then provisions a durable credential in this order:

1. A locally-generated RSA-2048 key-pair, registered on your Snowflake user with ALTER USER … SET RSA_PUBLIC_KEY in the first free slot and verified with a diagnostic connection.
2. If key-pair provisioning fails, a 365-day Programmatic Access Token (PAT).
3. If both fail, the CLI prints admin remediation SQL and exits without depositing a credential.

The resulting credential is deposited into the browser tab that generated the code and used to create the project. Raw short-lived OAuth tokens are never deposited.

qyra connect-snowflake --url <qyra-url> --code <one-time-code> --account <account>

Required options:

• --url <qyra-url>
  • The URL of your Qyra instance (for example https://app.qyraflow.com).
• --code <one-time-code>
  • The single-use connect code shown in the Snowflake connection form. Valid for 15 minutes.
• --account <account>
  • Your Snowflake account identifier (for example ecomstore-xy12345).

Optional overrides:

Any of these that you omit are resolved from your Snowflake session defaults or picked in the browser tab after the credential is deposited.

• --user <username> — Snowflake username override.
• --database <database> — default database.
• --warehouse <warehouse> — default compute warehouse.
• --role <role> — Snowflake role to use.
• --schema <schema> — default schema.

Example:

qyra connect-snowflake \
  --url https://app.qyraflow.com \
  --code 8f3c9a2b1e4d \
  --account ecomstore-xy12345

qyra config set-project

Choose the project you're developing in so the CLI knows which project content to look at for other commands like qyra validate and qyra preview. If your organization only has one project you won't need to use this!

qyra config set-project

This command will bring up an interactive list of projects in your organization to choose from.

If you need to set the project non-interactively, you can use one of the two optional arguments below.

Options:

• --name
  • Set the project non-interactively by passing an explicit project name
• --uuid
  • Set the project non-interactively by passing an explicit project UUID

Examples:

Set project to "Healthcare Demo":

qyra config set-project --name "Healthcare Demo"

Set project to the one with this UUID:

qyra config set-project --uuid "d75379bc-f6e9-4e52-86b2-d897cabacd0c"

qyra config get-project

Get the current active project that the CLI is configured to use.

qyra config get-project

This command displays the project that is currently set for CLI operations. Use this to verify which project will be affected by commands like qyra validate, qyra preview, and qyra deploy.

qyra config rename-project

Rename the currently selected project. This updates the project name in Qyra and also refreshes your local CLI context so subsequent commands use the new name.

qyra config rename-project --name "<new name>"

Use this after selecting a project with qyra config set-project when you want to change the display name without leaving the CLI. Check the current selection first with qyra config get-project.

This command only changes the project name. It does not modify warehouse connection settings or dbt configuration, and it does not trigger a recompile.

Options:

• --name <name> (required)
  • The new name for the selected project

Requirements:

• A project must already be selected via qyra config set-project.
• Your user must have a role with permission to update project details.

Example:

Rename the currently selected project to "Analytics":

qyra config rename-project --name "Analytics"

On success, the CLI prints a confirmation with the new project name.

qyra config list-projects

List all non-preview projects in your organization.

qyra config list-projects

This command displays all available projects (excluding preview projects) that you can select using qyra config set-project.

qyra compile

Compile Qyra resources using your local project and database credentials. dbt gets compiled first, then your Qyra explores. If you use dbt node selection to only compile a subset of models, Qyra will also compile models joined to those models to ensure no field references are broken.

All standard dbt options work with qyra compile.

Partial compilation

Qyra uses partial compilation by default. If an individual field, join, or set-validation failure can be isolated, Qyra records a warning, keeps the rest of the explore available, and prints the explore as PARTIAL_SUCCESS. Failures that cannot be isolated can still produce ERROR.

Use --no-partial-compilation when failures normally handled by partial compilation must be reported as errors instead. The flag does not promote unrelated, non-blocking warnings to errors. The strict compilation summary omits those remaining generic warnings, although deploy and preview commands can print them in the post-upload warning report. Warehouse-column errors remain blocking in both modes.

The flag is available on qyra compile, qyra validate, qyra deploy, qyra preview, and qyra start-preview. --ignore-errors still allows deploy and preview commands to continue after strict compilation errors.

Validate physical warehouse columns

Semantic compilation can verify Qyra field references, but it does not normally execute physical ${TABLE}.column references against your warehouse. Add --validate-warehouse-columns to run SELECT … WHERE 1 = 0 probes that return no rows. Whether a warehouse scans or bills for data is warehouse-dependent.

The scanner examines dimension and metric SQL in successfully compiled explores. It recognizes unquoted references containing letters, numbers, or underscores, such as ${TABLE}.order_id. Quoted references such as ${TABLE}."order id" are not checked, and tables whose relation contains a ${...} template are skipped.

A column rejected by the warehouse is reported as an error in both partial and strict compilation modes. After a batched probe fails, the CLI runs a zero-row relation-control probe. If a control probe fails for any reason, the CLI reports no column error because it cannot isolate a column-specific failure. An individual failed column probe is reported only when its follow-up control probe succeeds.

This validation requires a warehouse client and the warehouse catalog. --skip-warehouse-catalog disables it. The check is also skipped when no tables are selected, when compilation uses dbt Cloud CLI or a Qyra YAML-only project, or when qyra deploy automatically skips the warehouse catalog for a Spark target.

The flag is available on the same five compilation commands. qyra validate includes tables by default, so the check runs without --only. If you customize --only, keep tables in the list to run the warehouse check.

Options:

• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use types defined in the YAML
• --no-warehouse-credentials
  • (default: false)
  • Compile without any warehouse credentials. Skips dbt compile + warehouse catalog
• --validate-warehouse-columns
  • (default: false)
  • Validate supported physical ${TABLE}.column references against the warehouse
• --no-partial-compilation
  • Report failures normally handled by partial compilation as errors
• --disable-timestamp-conversion [true|false]
  • (default: false)
  • Snowflake only. Disable converting timestamps to UTC during compilation. Only use this if your timestamp values are already in UTC.

Examples:

Compile the whole project:

qyra compile

Compile only the accounts dbt model, then your Qyra explores:

qyra compile -s accounts

Compile your project, but skip dbt compile and warehouse catalog:

qyra compile --no-warehouse-credentials

qyra preview

Spin up a temporary preview project using your local project files and content (charts and dashboards) copied from your selected project.

All standard dbt options work with qyra preview.

Options:

• --name [preview name]
  • Custom name for the preview project. If a name is not provided, a unique, randomly generated name will be created
• --start-of-week [number]
  • Specifies the first day of the week (used by week-related date functions)
  • 0 (Monday) to 6 (Sunday)
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use types defined in the YAML
• --no-warehouse-credentials
  • (default: false)
  • Compile without any warehouse credentials. Skips dbt compile + warehouse catalog
• --use-dbt-list [true/false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json
• --validate-warehouse-columns
  • (default: false)
  • Validate supported physical ${TABLE}.column references against the warehouse
• --no-partial-compilation
  • Report failures normally handled by partial compilation as errors
• --ignore-errors
  • (default: false)
  • Allows deploy with errors on compile
• --table-configuration [prod/all]
  • (default: all)
  • If set to 'prod' it will copy the table configuration from the source project
• --skip-copy-content
  • (default: false)
  • Skip copying content from the source project
• --combine-manifest <path-or-url>
  • Path or http(s) URL to an additional dbt manifest.json. Models present in this file but missing from the preview-generated manifest are merged in so the preview reflects the full project even when dbt was only run on a subset of models. The preview-generated manifest always wins on conflicts. URLs (for example, a presigned S3 URL) are fetched at runtime so the manifest does not need to be downloaded first. Passing this overrides the manifest the CLI would otherwise fetch from Qyra.
• --no-combine
  • (default: false)
  • Skip fetching the upstream project's manifest from Qyra. By default the CLI fetches it and merges it into the preview, which is what makes models from a project's other dbt sources appear in the preview. Use this to preview only your local repo's models. Ignored when --combine-manifest is set.
• --use-batched-deploy
  • (default: false)
  • Deploy explores in batches instead of a single request. Useful for large projects that exceed payload size limits
• --batch-size [number]
  • (default: 50)
  • Number of explores to include in each batch when using batched deploy
• --parallel-batches [number]
  • (default: 1)
  • Number of batches to upload in parallel when using batched deploy. Use with caution as higher values may overwhelm the server
• --expires-in <hours>
  • (default: the upstream project's configured default, or 720 if there is no upstream project)
  • Number of hours until the preview project auto-expires. Values above the upstream project's maximum preview expiration are silently capped to the maximum.
• --disable-timestamp-conversion [true|false]
  • (default: false)
  • Snowflake only. Disable converting timestamps to UTC. Applied and persisted when creating the preview project. When updating an existing preview, the flag is ignored with a warning and the saved project setting is used instead.

Examples:

Create a temporary preview project with the name PR: Add Revenue Metric and ignore validation errors while spinning it up:

qyra preview --name "PR: Add Revenue Metric" --ignore errors

Create a temporary preview project with a random name and set the start of week to Monday, only include models with the dbt tag of marketing:

qyra preview --start-of-week=0 --select "tag:marketing"

qyra start-preview

Create a persistent preview project using your local project files and content (charts and dashboards) copied from your selected project.

All standard dbt options work with qyra start-preview.

Required argument:

• --name [preview name]
  • Name for the preview project. If a preview project with this name already exists, it will be updated, otherwise it will create a new preview project.

Options:

• --start-of-week [number]
  • Specifies the first day of the week (used by week-related date functions)
  • 0 (Monday) to 6 (Sunday)
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use the types defined in YAML
• --use-dbt-list [true/false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json
• --validate-warehouse-columns
  • (default: false)
  • Validate supported physical ${TABLE}.column references against the warehouse
• --no-partial-compilation
  • Report failures normally handled by partial compilation as errors
• --ignore-errors
  • (default: false)
  • Allows deploy with errors on compile
• --table-configuration [prod/all]
  • (default: all)
  • If set to 'prod' it will copy the table configuration from the source project
• --skip-copy-content
  • (default: false)
  • Skip copying content from the source project
• --combine-manifest <path-or-url>
  • Path or http(s) URL to an additional dbt manifest.json. Models present in this file but missing from the preview-generated manifest are merged in so the preview reflects the full project even when dbt was only run on a subset of models. The preview-generated manifest always wins on conflicts. URLs (for example, a presigned S3 URL) are fetched at runtime so the manifest does not need to be downloaded first. Passing this overrides the manifest the CLI would otherwise fetch from Qyra.
• --no-combine
  • (default: false)
  • Skip fetching the upstream project's manifest from Qyra. By default the CLI fetches it and merges it into the preview, which is what makes models from a project's other dbt sources appear in the preview. Use this to preview only your local repo's models. Ignored when --combine-manifest is set.
• --use-batched-deploy
  • (default: false)
  • Deploy explores in batches instead of a single request. Useful for large projects that exceed payload size limits
• --batch-size [number]
  • (default: 50)
  • Number of explores to include in each batch when using batched deploy
• --parallel-batches [number]
  • (default: 1)
  • Number of batches to upload in parallel when using batched deploy. Use with caution as higher values may overwhelm the server
• --expires-in <hours>
  • (default: the upstream project's configured default, or 720 if there is no upstream project)
  • Number of hours until the preview project auto-expires. Values above the upstream project's maximum preview expiration are silently capped to the maximum.
• --disable-timestamp-conversion [true|false]
  • (default: false)
  • Snowflake only. Disable converting timestamps to UTC. Applied and persisted when creating the preview project. When updating an existing preview, the flag is ignored with a warning and the saved project setting is used instead.

qyra stop-preview

Shuts down a project that was created with .

This command does not support using dbt options.

Required argument:

• --name [preview name]
  • Name of the preview project to be deleted.

Example:

Shut down the preview project named neon unicorn.

qyra stop-preview "neon unicorn"

qyra deploy

Compiles and deploys the current project to your selected Qyra Cloud project.

All standard dbt options work with qyra deploy.

Options:

• --create [project_name]
  • Create a new project. If a project name is not provided, you'll be prompted for one on creation
• --ignore-errors
  • (default: false)
  • Allows deploy with errors on compile
• --start-of-week [number]
  • Specifies the first day of the week (used by week-related date functions)
  • 0 (Monday) to 6 (Sunday)
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use types defined in the YAML
• --no-warehouse-credentials
  • (default: false)
  • Compile without any warehouse credentials. Skips dbt compile + warehouse catalog
• --use-dbt-list [true|false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json
• --combine-manifest <path-or-url>
  • Path or http(s) URL to an additional dbt manifest.json. Models present in this file but missing from the deploy-generated manifest are merged in so the deploy reflects the full project even when dbt was only run on a subset of models. The deploy-generated manifest always wins on conflicts. URLs (for example, a presigned S3 URL) are fetched at runtime so the manifest does not need to be downloaded first. Unlike preview and start-preview, deploy never fetches a manifest from Qyra on its own, so this flag is the only way to combine one.
• --validate-warehouse-columns
  • (default: false)
  • Validate supported physical ${TABLE}.column references against the warehouse
• --no-partial-compilation
  • Report failures normally handled by partial compilation as errors
• --use-batched-deploy
  • (default: false)
  • Deploy explores in batches instead of a single request. Useful for large projects that exceed payload size limits
• --batch-size [number]
  • (default: 50)
  • Number of explores to include in each batch when using batched deploy
• --parallel-batches [number]
  • (default: 1)
  • Number of batches to upload in parallel when using batched deploy. Use with caution as higher values may overwhelm the server
• --disable-timestamp-conversion [true|false]
  • (default: false)
  • Snowflake only. Disable converting timestamps to UTC. Only honored together with --create; the value is persisted to the new project. When deploying to an existing project, the flag is ignored with a warning and the saved project setting is used instead.

Examples:

Create a new project that uses the production credentials from your local dbt profiles.yml:

qyra deploy --create --target production

Deploy a large project with many explores using batched deploy:

qyra deploy --use-batched-deploy

Deploy with custom batch settings for very large projects:

qyra deploy --use-batched-deploy --batch-size 100 --parallel-batches 3

Deploy a subset of models while keeping the rest of the project intact by merging in an existing manifest:

qyra deploy --select "tag:marketing" --combine-manifest ./prod-manifest.json

qyra refresh

Refreshes your hosted Qyra project using the latest code from your linked Github repository. This is equivalent to pressing Refresh dbt in the UI as an admin.

This command does not support using dbt options.

qyra deploy vs qyra refresh

The two CLI commands above (qyra deploy and qyra refresh) are often confused. Here's the quick difference:

Rule of thumb:

• Local dbt code you want to push → deploy
• Qyra already points at a git repo and you just want it to pull the latest → refresh

qyra validate

Validates a project by comparing the content in your currently selected project against your local project files. Returns all charts and dashboards that have errors.

All standard dbt options work with qyra validate.

Options:

• --project [project uuid]
  • Project UUID to validate, if not provided, the last preview will be used
• --preview
  • (default: false)
  • Validate the last preview if available
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and deploy from the existing ./target/manifest.json
• --skip-warehouse-catalog
  • (default: false)
  • Skip fetch warehouse catalog and use types defined in the YAML
• --use-dbt-list [true/false]
  • (default: true)
  • Use dbt list instead of dbt compile to generate dbt manifest.json
• --only [elems...]
  • (default: ["charts","dashboards","tables"])
  • Specify project elements to validate
• --severity <level>
  • (default: "error")
  • Minimum issue level that fails the command. error reports validation errors only and hides chart configuration warnings. warning also reports chart configuration warnings and treats them as errors, so the command exits with return code 1 when any warning exists. See Treat warnings as errors
• --validate-warehouse-columns
  • (default: false)
  • Validate supported physical ${TABLE}.column references. Tables are included in validation by default; when using --only, the list must include tables
• --no-partial-compilation
  • Report failures normally handled by partial compilation as errors
• --include-spaces <spaceSlugs...>
  • Only report chart and dashboard validation errors from these spaces. Matching cascades recursively into sub-spaces via parent space relationships, so passing a parent space slug also includes everything under it. Use the same spaceSlug identifiers that appear in qyra download output. Space slugs aren't unique — if the same slug exists in multiple spaces, all of them (and their sub-spaces) are matched. Mutually exclusive with --exclude-spaces.
• --exclude-spaces <spaceSlugs...>
  • Skip chart and dashboard validation errors from these spaces (and their sub-spaces, applied recursively). Everything else is reported. Mutually exclusive with --include-spaces.

Examples:

Validate only dashboards and use the existing compiled dbt manifest:

qyra validate --only ["dashboards"] --skip-dbt-compile

Validate production content only, so errors in an archive space don't fail CI:

qyra validate --exclude-spaces archive

Validate a single space and everything nested under it:

qyra validate --include-spaces orders

qyra generate

Generates a new schema.yml file or updates existing schema.yml for selected model(s). Use this command to auto-generate Qyra-ready YAML schema files from your database columns so your dbt models appear as tables in Qyra.

All standard dbt options work with qyra generate.

Options:

• -y or --assume-yes
  • (default: false)
  • assume yes to prompts
• --exclude-meta
  • (default: false)
  • exclude Qyra metadata from the generated .yml
• --preserve-column-case
  • (default: false)
  • preserve original casing of column names in generated schema files
• --skip-existing
  • (default: false)
  • skip files that already exist

Example:

Generate or update YAML file for a single dbt model to cover all columns in the database:

qyra generate -s mymodel

qyra generate-exposures

Generates a schema.yml file for Qyra exposures.

This command does not support using dbt options.

Options:

• --project-dir [path]
  • (default: ".")
  • The directory of the dbt project
• --output [path]
  • The path where the output exposures YAML file will be written

Example:

Create or update YAML file called qyra-exposures.yml in the current directory with all exposures in Qyra:

qyra generate-exposures --output ./qyra-exposures.yml

qyra dbt run

Runs dbt and then generates or updates schema.yml file(s) for models that have columns missing or changed from the existing schema.yml files.

Any dbt option that works with dbt run will also work with qyra dbt run. That includes all the Qyra dbt options, and more (see dbt run docs).

Options:

• --exclude-meta
  • (default: false)
  • exclude Qyra metadata from the generated .yml
• --assume-yes or -y
  • assume yes to prompts (default: false)
• --assume-no or -no
  • assume no to prompts (default: false)
• --preserve-column-case
  • (default: false)
  • preserve original casing of column names in generated schema files

Example:

Run a single model and create or update its schema.yml file:

qyra dbt run --select mymodel

qyra download

Downloads all charts and dashboards from your Qyra project as code. A qyra directory is created in your working directory and all of the charts and dashboards are written there as .yml files.

E.g. if you're running this command inside your dbt directory (eg: /home/javi/dbt) then it will create a folder (/home/javi/dbt/qyra).

You can make changes to the code and upload these changes back to your Qyra project. Content that's been downloaded as code can still be managed in the Qyra UI.

Options:

• --charts or -c
  • select specific charts as code to download from your project. Use the chart SLUG, UUID or URL to specify the chart
• --dashboards or -d
  • select specific dashboards as code to download from your project. This will also download all charts in the dashboard as code. Use the dashboard SLUG, UUID or URL to specify the dashboard
• --path or -p
  • specify a custom path to a directory where you want the downloaded files to be written to. You can use the full path, or a relative path to a directory
• --project <project uuid>
  • download all charts and dashboards from a specific project. You can find the project UUID for a project from a Qyra URL. E.g. here, the project UUID is 123-project-uuid https://app.qyraflow.com/projects/123-project-uuid/
• --language-map or -l
  • (default: false)
  • generate <item name>.language.map.yml for the downloaded charts and dashboards with all translatable text from charts and dashboards
• --nested
  • (default: false)
  • split downloaded content into sub-folders matching the spaces in your project
• --skip-spaces
  • (default: false)
  • skip downloading .space.yml files (space metadata and access policies). Use this when you only want to reconcile charts and dashboards.
• --spaces-only
  • (default: false)
  • download only .space.yml files — no charts or dashboards. Useful for permission-only PRs and cross-instance access promotions. Strict: has no chart/dashboard fallback if the access-aware space endpoint is unavailable.
• --root-spaces
  • (default: false)
  • write new flat .space.yml downloads at the qyra/ root instead of qyra/spaces/ (legacy layout). Existing files are always updated in place regardless of this flag. Cannot be combined with --nested.
• --strip-pivot-series
  • (default: false)
  • strip per-value pivot series config from chart YAML so it's portable across projects. Cartesian chart series that are tied to specific pivot field values are rewritten to reference only the underlying x/y fields, and duplicates collapsed into a single entry. Use this when the source project's pivot values don't exist in the target project (for example, when reusing chart YAML as a template), so the upload doesn't fail or render with the original project's hardcoded series. Only applies to regular charts; SQL charts and dashboards are unaffected.
• --virtual-views <slugs...>
  • opt-in flag to download specific virtual views as code. Pass one or more virtual-view slugs. Each view is written to qyra/virtual-views/<slug>.yml. Virtual views are not included in a bare qyra download — use this flag or --include-virtual-views to opt in.
• --include-virtual-views
  • (default: false)
  • opt-in flag to download every virtual view in the project as code. Use --virtual-views <slugs...> instead when you only want specific views.
• --apps <refs...>
  • opt-in flag to also download specific data apps as code (enterprise only). Pass one or more app references — a slug, UUID, or app URL. Works for apps that haven't been added to a space, and is never capped. Each app is written to qyra/apps/<slug>/ as a locally buildable project: qyra-app.yml manifest (with the app's slug, name, description, and linked external connections), the app's src/ tree, package.json / pnpm-lock.yaml, local build scaffolding (vite.config.js, tsconfig.json, index.html), a read-only .qyra/context/ snapshot of the project's semantic layer, and agent skill files (AGENTS.md, .claude/skills/). The built output is not included — the server rebuilds it on upload. Dashboards you download bring their referenced data apps along automatically. Custom chart types are a separate resource: an --apps ref that points at a chart type is skipped with a warning — download it with --chart-types instead.
• --include-apps
  • (default: false)
  • opt-in flag to download every data app in the project as code (enterprise only), capped at --apps-limit. Use --apps <refs...> to fetch a specific set instead.
• --apps-limit <n>
  • (default: 50)
  • cap on the number of apps returned by --include-apps.
• --apps-only
  • (default: false)
  • download only data apps, skipping charts, dashboards, and space files (implies --skip-charts --skip-dashboards --skip-spaces). Requires --apps <refs...> or --include-apps. Recommended for app-focused checkouts. Cannot be combined with --chart-types-only.
• --chart-types <refs...>
  • opt-in flag to also download specific custom chart types as code (enterprise only). Pass one or more references — a slug, UUID, or chart type URL. Each chart type is written to qyra/chart-types/<slug>/ with the same locally buildable layout as a data app folder, and its qyra-app.yml manifest carries a vizSchema field with the chart type's declared inputs so it round-trips to the destination on upload. A ref that points at a data app is skipped with a warning — download it with --apps instead. Charts you download bring the chart types they render with along automatically, since a chart file without its chart type can't be uploaded elsewhere.
• --include-chart-types
  • (default: false)
  • opt-in flag to download every custom chart type in the project as code (enterprise only), capped at --chart-types-limit. Use --chart-types <refs...> to fetch a specific set instead.
• --chart-types-limit <n>
  • (default: 50)
  • cap on the number of chart types returned by --include-chart-types.
• --chart-types-only
  • (default: false)
  • download only custom chart types, skipping charts, dashboards, and space files (implies --skip-charts --skip-dashboards --skip-spaces). Bare --chart-types-only downloads every chart type in the project; pass --chart-types <refs...> to select a subset. Cannot be combined with --apps-only.
• --external-connections <slugs...>
  • opt-in flag to download specific external connection definitions to qyra/external-connections/<slug>.yml. Secrets are never written to disk — provide them via environment variables on upload.
• --include-external-connections
  • (default: false)
  • opt-in flag to download every external connection definition in the project.
• --skip-charts
  • (default: false)
  • skip downloading charts (including SQL charts)
• --skip-dashboards
  • (default: false)
  • skip downloading dashboards
• --agents <slugs...>
  • opt-in flag to also download specific AI agents as code. Pass one or more agent slugs or UUIDs. Files are written to qyra/ai-agents/<slug>.yml and include evaluation suite definitions and prompts, but never evaluation run history. See AI agents as code for the YAML schema and lifecycle rules.
• --include-agents
  • (default: false)
  • opt-in flag to download every AI agent in the project as code. The endpoint is paginated, so the CLI walks all pages automatically. Agent files are written to qyra/ai-agents/. Bare qyra download does not include agents.
• --organization
  • (default: false)
  • switch to organization mode and download organization-scoped content — custom roles, users, groups, and data app themes — instead of project content. Files are written to qyra/custom-roles/<role-slug>.yml, qyra/users/<email-slug>.yml, qyra/groups/<group-slug>.yml, and qyra/themes/<theme-slug>/. Theme packages are staged and validated before the local themes/ directory is replaced, so a failed theme download preserves the previous local theme set. A successful download removes local theme directories that no longer exist remotely. Requires organization admin permissions. If the groups feature is disabled on the instance, the groups folder is skipped (run with --verbose for the explanation). Cannot be combined with project-content flags such as --charts, --dashboards, --project, or --nested.

Examples:

Download all charts and dashboards from your project.

qyra download

Download a specific dashboard from your Qyra project.

qyra download -d https://app.qyraflow.com/my-dashboard-url

Download all content from a project to the directory /Users/katiehindson/qyra/qyra-analytics/

qyra download -p /Users/katiehindson/qyra/qyra-analytics/

This will create: /Users/katiehindson/qyra/qyra-analytics/charts/ and /Users/katiehindson/qyra/qyra-analytics/dashboards and save the content to these new folders.

You can also use relative paths like:

qyra download -p ../

Download all charts and dashboards organized by space.

qyra download --nested

Download all charts and dashboards from a specific project with language maps.

qyra download --project 21eef0b9-5bae-40f3-851e-9554588e71a6 -l

Download charts with portable, pivot-value-free YAML (handy when reusing charts as templates in projects that don't share the same pivot values).

qyra download --strip-pivot-series

Download all charts and dashboards, plus every data app in a space (up to the first 10).

qyra download --include-apps

Download specific data apps by UUID (charts and dashboards are still downloaded as usual). Required for apps that are not in a space.

qyra download --apps 8f2b1c4d-1111-2222-3333-444455556666 a1b2c3d4-5555-6666-7777-888899990000

Download just one data app and nothing else.

qyra download --apps-only --apps 8f2b1c4d-1111-2222-3333-444455556666

Download all charts and dashboards, plus every custom chart type in the project (up to the first 50).

qyra download --include-chart-types

Download just one custom chart type and nothing else, by slug.

qyra download --chart-types-only --chart-types calendar-heatmap

Download every AI agent in the project alongside charts and dashboards.

qyra download --include-agents

Download only a specific AI agent by slug (or UUID).

qyra download --agents orders-support-agent

Download all charts and dashboards, plus every virtual view in the project.

qyra download --include-virtual-views

Download only specific virtual views by slug.

qyra download --virtual-views orders_enriched customers_enriched

Download every organization-scoped resource as code — custom roles, users, groups, and data app themes (requires org admin).

qyra download --organization

qyra upload

Uploads charts and dashboards that you've made changes to from the qyra/ directory in your dbt project to your Qyra project. To upload new content as code to your project, you need to use the option --force (see Options below).

If there have been changes made to a chart or dashboard in the application that is being uploaded from code, qyra upload will overwrite the changes.

Options:

• --force
  • required to create new content as code that doesn't exist in your Qyra project yet — without it, qyra upload only updates existing content. Also required to apply destructive virtual view column changes (removing a column or changing its type).
• --charts or -c
  • select specific charts as code to upload back to your project. Use the chart SLUG to specify the chart
• --dashboards or -d
  • select specific dashboards as code to upload back to your project. Use the dashboard SLUG to specify the dashboard
• --path or -p
  • specify a custom path to a directory where the files you want to upload are. You can use the full path, or a relative path to a directory
• --project <project uuid>
  • upload all charts and dashboards from a specific project. You can find the project UUID for a project from a Qyra URL. E.g. here, the project UUID is 123-project-uuid https://app.qyraflow.com/projects/123-project-uuid/
• --skip-space-create
  • (default: false)
  • Skip space creation if it does not exist
• --skip-spaces
  • (default: false)
  • skip uploading .space.yml files. Charts and dashboards still upload as normal, and existing space permissions are left untouched.
• --spaces-only
  • (default: false)
  • upload only .space.yml files — no charts or dashboards. Spaces are always uploaded before dependent content, so this is the right flag for a permissions-only promotion between environments. Replacing a space's access policy requires actual manage:Space on the resolved space; broad manage:ContentAsCode alone doesn't bypass restricted-space authorization.
• --include-charts
  • (default: false)
  • Include charts updates when uploading dashboards
• --public
  • (default: false)
  • Creates new spaces as public instead of private
• --validate
  • (default: false)
  • Validate charts and dashboards after upload and display any validation errors
• --nested
  • (default: false)
  • expect content to be organized in sub-folders matching the spaces in your project (use this if content was downloaded with --nested)
• --virtual-views <slugs...>
  • specify virtual view slugs to upload from qyra/virtual-views/. Combine with --force to apply destructive column changes.
• --skip-virtual-views
  • (default: false)
  • skip uploading virtual views, even when qyra/virtual-views/ contains files
• --apps [refs...]
  • opt-in flag to also upload data apps as code (enterprise only). Pass one or more refs (slugs, or legacy UUIDs) to upload just those app folders, or use --include-apps to upload every folder under qyra/apps/. The CLI posts each app's src/ tree and manifest and returns immediately — the destination rebuilds the app in its sandbox and publishes a new version. The app shows a building status in the UI until the build finishes. Identity is the manifest's slug, upserted in the target project: an existing slug appends a new version (and applies edits to name / description); a new slug creates a new app. If the source, dependencies, and viz schema are byte-for-byte identical to the latest version, the upload is skipped with matches v<n> (name/description edits still apply); pass --force to rebuild anyway. Each project runs at most 5 app builds concurrently — if the cap is hit, the CLI waits automatically (up to 10 minutes of consecutive waiting) instead of failing. A folder under qyra/apps/ that is actually a custom chart type is skipped with a warning — move it to qyra/chart-types/ and upload it with --chart-types. Uploading requires the create:DataApp scope, which is granted to Editor, Developer, and Admin roles. Users with only create:DataApp@preview can upload apps to preview projects they created themselves, but not to production or to previews created by teammates. Dashboards you upload push their referenced app folders first, even without --apps.
• --include-apps
  • (default: false)
  • upload every app folder under qyra/apps/.
• --apps-only
  • (default: false)
  • upload only data apps, skipping charts, dashboards, and space reconciliation. Bare --apps-only uploads every app folder in qyra/apps/; pass --apps <refs...> to select a subset. Recommended for app-focused CI runs.
• --app-space <spaceRef>
  • space (slug or UUID) that new data apps created by this upload land in. Existing apps keep the space they already have. Without this flag, new apps go to the target project's default location. The space must already exist in the target project — resolve slugs to a single match, or pass the space UUID directly.
• --chart-types <refs...>
  • opt-in flag to also upload custom chart types as code (enterprise only). Pass one or more refs — a slug (the folder name), UUID, or chart type URL — to upload just those folders from qyra/chart-types/, or use --include-chart-types to upload every folder there. Uploads work like data app uploads: identity is the manifest's slug, upserted in the target project, the server rebuilds from source, unchanged uploads are skipped, and the same create:DataApp scope is required. The manifest's vizSchema is sent alongside the source and persisted on the new version. Chart types are project-global and spaceless, so --app-space doesn't apply to them. Unlike dashboard-referenced apps, chart types are never auto-pushed: uploading a chart whose chart type is missing in the target project fails with a message to upload the chart type first.
• --include-chart-types
  • (default: false)
  • upload every chart type folder under qyra/chart-types/.
• --chart-types-only
  • (default: false)
  • upload only custom chart types, skipping charts, dashboards, and space reconciliation. Bare --chart-types-only uploads every folder in qyra/chart-types/; pass --chart-types <refs...> to select a subset. Cannot be combined with --apps-only.
• --allow-custom-dependencies
  • (default: false)
  • approve uploading apps that declare custom dependencies without prompting. Required for non-interactive runs (CI) of apps that add packages beyond the template's base dependencies — without it, the CLI skips those apps with a per-app warning and counts them as failures.
• --create-new
  • (default: false)
  • always create a new data app (with a freshly generated slug) from the uploaded source instead of updating the app the manifest references. Useful for forking an app inside the same project.
• --agents <slugs...>
  • upload only the AI agent files matching these slugs from qyra/ai-agents/. Omit to upload every agent file in that folder. Upload is idempotent — the server creates missing agents, updates existing agents by slug, and leaves unchanged agents alone. Evaluation suites declared in a file are upserted by title, while undeclared suites remain unchanged. See AI agents as code.
• --skip-agents
  • (default: false)
  • skip uploading AI agents even when qyra/ai-agents/ contains files. Use this to keep an agents folder in your repo without pushing changes on every qyra upload.
• --organization
  • (default: false)
  • switch to organization mode and upload organization-scoped content — custom roles, users, groups, and data app themes — instead of project content. The CLI validates every local theme before making any organization change, then applies custom roles, users, groups, and themes in that order. Document resources are upserted by role name, primary email, or group name; themes are upserted by manifest slug and skipped when unchanged. A missing or empty qyra/themes/ directory is a no-op, and removing one theme directory never deletes the remote theme. Theme imports preserve the organization default and are atomic per theme, not per batch. Requires organization admin permissions. Cannot be combined with project-content flags such as --charts, --dashboards, --project, or --force. Uploads never delete roles, users, groups, or themes.
• --send-invites
  • (default: false)
  • only valid with --organization. When uploading users, send invitation emails to eligible staged users. Users who have already authenticated, are disabled, or already have a valid outstanding invitation are skipped. Without this flag, users authenticate through the instance's existing domain, SSO, or manually triggered invitation flows — credentials are never carried in the YAML.

Examples:

Upload all charts and dashboards in code from your qyra/ directory to your Qyra project.

qyra upload

Upload a specific dashboard to your Qyra project.

qyra upload -d my-dashboard-slug

Upload a specific dashboard and include any chart changes referenced by that dashboard.

qyra upload -d my-dashboard-slug --include-charts

Upload content from the directory /Users/katiehindson/qyra/qyra-analytics/

qyra upload -p /Users/katiehindson/qyra/qyra-analytics/

This will upload all content from: /Users/katiehindson/qyra/qyra-analytics/charts/ and /Users/katiehindson/qyra/qyra-analytics/dashboards and save the content to these new folders.

You can also use relative paths like:

qyra upload -p ../

Upload all charts and dashboards from your qyra/ directory to a specific project.

qyra upload --project 21eef0b9-5bae-40f3-851e-9554588e71a6

Upload all charts and dashboards and validate them after upload to check for errors.

qyra upload --validate

Upload a specific virtual view.

qyra upload --virtual-views orders_enriched

Apply a destructive virtual view change (removing a column or changing its type) — the CLI blocks this unless --force is passed.

qyra upload --virtual-views orders_enriched --force

Upload all charts, dashboards, and data app folders under qyra/apps/.

qyra upload --apps

Upload only specific data apps by UUID.

qyra upload --apps 8f2b1c4d-1111-2222-3333-444455556666

Copy a data app to a different project as a brand-new app (non-interactive).

qyra upload --apps --project 21eef0b9-5bae-40f3-851e-9554588e71a6 --create-new

Upload only a specific custom chart type by slug (the folder name under qyra/chart-types/).

qyra upload --chart-types calendar-heatmap

Upload every chart type folder and nothing else.

qyra upload --chart-types-only

Upload every AI agent file under qyra/ai-agents/ (creates missing agents, updates existing ones by slug).

qyra upload

Upload only a specific AI agent by slug.

qyra upload --agents orders-support-agent

Upload every organization-scoped resource — custom roles, users, groups, and data app themes — back to the organization (requires org admin).

qyra upload --organization

Upload organization resources and also send invitation emails to any staged users who need to authenticate.

qyra upload --organization --send-invites

qyra slug-update

Renames a chart slug in Qyra and updates the corresponding files in your local content-as-code directory.

qyra slug-update --from old-chart-slug --to new-chart-slug

A successful rename:

• changes the chart's canonical slug and URL in Qyra;
• keeps the previous slug as an alias, so existing links continue working;
• updates the chart YAML slug and filename;
• updates saved-chart references in dashboard YAML;
• updates chart references in scheduled deliveries, alerts, and Google Sheets syncs;
• updates chart language-map files and .qyra-metadata.json, when present.

You do not need to run qyra upload afterward. The command updates Qyra first and then updates the local files. If you keep content in Git, review and commit the resulting file changes.

Options:

• --from <slug>
  • required; the chart's current canonical slug, or its previous slug when safely retrying the same rename.
• --to <slug>
  • required; the new slug. Slugs contain lowercase letters, numbers, and hyphen-separated words.
• --path <path>
  • use a custom content-as-code directory instead of the default qyra/ directory in your current working directory.
• --project <project uuid>
  • rename the chart in a specific project instead of your currently selected project.
• --dry-run
  • preview the intended slug change and list the local files that would change without renaming the chart or writing files.
• --verbose
  • show detailed command output.

Examples:

Preview a rename and its local file changes:

qyra slug-update --dry-run --from copy-of-orders --to orders
Rename a chart and update a custom content-as-code directory:
```bash
qyra slug-update \
  --from copy-of-orders \
  --to orders \
  --path ./analytics-content

The command is idempotent. Re-running the same rename safely completes any missing local updates. You can also rename a chart back to one of its previous slugs; the slug you replace becomes the new alias.

Aliases reserve their slugs within the project. Creating or uploading another chart with a current or historical slug uses the existing chart or generates a different unique slug instead of creating an ambiguous duplicate.

qyra apps create

Scaffold a new data app folder locally. The app is created on the server on your first qyra upload.

The command derives a slug from the name, checks it's available in the target project, then installs the template's npm packages and generates the shadcn UI components locally — Node.js 20+ (with npm) is required.

qyra apps create <name>

Options:

• --description <text>
  • set the app description in the manifest.
• --slug <slug>
  • override the slug derived from the name. Must match [a-z0-9-] and start with an alphanumeric character.
• --project <project uuid>
  • the project the app will use (default: your selected project).
• --path <path> or -p
  • Qyra content root (default: ./qyra).
• --assume-yes or -y
  • skip the npm-install confirmation prompts, useful in scripts.

Examples:

Scaffold a new app in your selected project.

qyra apps create "Revenue explorer"

Scaffold an app with a custom slug and description.

qyra apps create "Revenue explorer" --slug revenue-v2 --description "New pricing model exploration"

qyra apps preview

Preview a downloaded (or locally created) data app on your machine against a real Qyra instance, authenticated as you. Starts the Vite dev server with a loopback proxy that forwards the app's API calls to Qyra — your API key never reaches the app or the browser. Requires npm install in the app folder first.

qyra apps preview [path]

Argument:

• [path]
  • the app folder to preview (default: the current directory).

Options:

• --project <project uuid>
  • preview against a specific project (default: the manifest's projectUuid).
• --url <url>
  • Qyra server URL (default: your login config).
• --token <token>
  • API key (default: your login config). Prefer qyra login or QYRA_API_KEY — --token leaks into shell history.

Examples:

Preview from inside the app folder.

cd qyra/apps/revenue-explorer
npm install
qyra apps preview

Preview a different app by passing its path.

qyra apps preview qyra/apps/marketing-funnel

qyra apps validate

Validate one or more data apps locally. Checks the app manifest (qyra-app.yml), dependencies (package.json and pnpm-lock.yaml), source files under src/, external connection aliases, and semantic-layer references used in code.

By default, semantic references are checked against the downloaded semantic-layer snapshot in each app's .qyra/context/ folder. Pass --live to check against fresh explores fetched from the app's project instead.

Exits non-zero if any app has errors, so you can wire it into pre-commit hooks or CI.

qyra apps validate [paths...]

Argument:

• [paths...]
  • one or more app folders to validate together (default: the current directory).

Options:

• --live
  • validate semantic-layer references against fresh explores from each app's project instead of the local snapshot. Requires a project selected via qyra config set-project.
• --format <format>
  • output format: human (default) or json.
• --verbose
  • print additional diagnostic output.

Examples:

Validate the app in the current folder against its local semantic-layer snapshot.

cd qyra/apps/revenue-explorer
qyra apps validate

Validate multiple apps at once.

qyra apps validate qyra/apps/revenue-explorer qyra/apps/marketing-funnel

Validate all your apps.

qyra apps validate qyra/apps/*

Validate against live explores from the project.

qyra apps validate --live

Emit a machine-readable report for CI.

qyra apps validate --format json

qyra rename

Rename model or field names across all content in your Qyra project. This command will do a full find and replace on a field or table so all references in chart fields, dashboard filters, table calculations, custom metrics, etc. can be changed at once.

Arguments:

• --type
  • Specify what you're renaming
  • Accepted values: field or model
• --from
  • The current name of the table or field you want to change (this is the slug from your YAML definition, i.e. num_users)
• --to
  • The new name you want to use (must match the new slug in your YAML for this field or table, i.e. count_distinct_user_id)

Options:

• --project, -p
  • Project UUID to target a specific project
  • (default: The most recent project you set with qyra config set-project)
• --model, -m
  • The model to target for field renaming. This is only needed if the current field name is not unique in your project
• --dry-run
  • List all content the rename action will change, no changes will be made
• --list
  • List all charts and dashboards that were renamed after the command is complete
• --assume-yes, -y
  • Assume yes to all prompts.

Examples:

Rename the field num_users to count_distinct_user_id.

qyra rename --type field --from num_users --to count_distinct_user_id

Do a dry run of changing the table reference from users_mart_v1 to users.

qyra rename --type model --from users_mart_v1 --to users --dry-run

Rename the field count to count_distinct_order_id in the orders model and list all affected content when complete:

qyra rename --type field --model orders --from count --to count_distinct_order_id --list

qyra diagnostics

Shows diagnostic information about the CLI environment. This is useful for debugging issues with the CLI or sharing information with the Qyra support team.

qyra diagnostics

Options:

• --dbt
  • Include dbt debug information in the output
• --project-dir <path>
  • dbt project directory (used with --dbt flag)
• --profiles-dir <path>
  • dbt profiles directory (used with --dbt flag)
• --defer
  • dbt defer option (used with --dbt flag)
• --no-defer
  • dbt no-defer option (used with --dbt flag)

Information displayed:

• CLI version
• Node.js version and optimization status
• Authentication status (API key, server URL, organization, project)
• dbt debug output (if --dbt flag provided)

Examples:

Show basic diagnostic information:

qyra diagnostics

Show diagnostic information including dbt debug output:

qyra diagnostics --dbt

Show diagnostic information with dbt debug for a specific project directory:

qyra diagnostics --dbt --project-dir ./my-dbt-project

qyra sql

Run a raw SQL query against your data warehouse using the credentials from your currently selected project. Results are exported to a CSV file.

qyra sql <query> -o <output_file>

Required argument:

• <query>
  • The SQL query to execute

Required option:

• -o, --output <file>
  • Output file path for CSV results

Options:

• --limit <number>
  • Maximum number of rows to return from the query
• --page-size <number>
  • Number of rows per page (default: 500, max: 5000)
• --verbose
  • (default: false)
  • Show detailed output

Examples:

Run a simple query and save results to a CSV file:

qyra sql "SELECT * FROM users LIMIT 100" -o users.csv

Run a query with a row limit:

qyra sql "SELECT * FROM orders" -o orders.csv --limit 1000

Run a query with verbose output to see detailed progress:

qyra sql "SELECT customer_id, SUM(amount) FROM orders GROUP BY 1" -o revenue.csv --verbose

qyra warehouse-catalog

Discover the databases, schemas, tables, and fields available in the warehouse connected to your currently selected project. The command calls Qyra using the project's server-side warehouse credentials, so you don't need a local warehouse connection or a profiles.yml — just a valid Qyra login and a selected project.

Use it to explore your warehouse before writing dbt models or Qyra explores, to look up the Qyra-inferred type of a column, or to pipe a deterministic list of tables and fields into scripts and AI agents via --json.

qyra warehouse-catalog [options]

By default, the command prints a human-readable table of every database.schema.table in the project's cached warehouse catalog. Use the filter flags to narrow the list, --include-fields to also list the columns of a single fully qualified table, and --json for machine-readable output.

Options:

• --database <name>
  • Filter by exact database name
• --schema <name>
  • Filter by exact schema name
• --table <name>
  • Filter by exact table name
• --include-fields
  • (default: false)
  • Also list each field's name and Qyra-inferred type (number, string, boolean, date, timestamp, …). Requires --database, --schema, and --table so exactly one table is targeted.
• --refresh
  • (default: false)
  • Refetch warehouse metadata and refresh the server-side catalog cache before listing. Use this when tables have been added or removed since the catalog was last cached.
• --json
  • (default: false)
  • Emit deterministic JSON instead of a terminal table. Handy for piping into jq or feeding to a script.
• --verbose
  • (default: false)
  • Show detailed API request output

Examples:

List every database, schema, and table in the project's warehouse catalog:

qyra warehouse-catalog

Narrow to a single schema:

qyra warehouse-catalog --database jaffle --schema analytics

List the fields and Qyra types on a fully qualified table:

qyra warehouse-catalog --database jaffle --schema analytics --table orders --include-fields

Refresh the server-side catalog cache before listing (useful right after adding new warehouse tables):

qyra warehouse-catalog --refresh

Emit JSON and extract distinct database names with jq:

qyra warehouse-catalog --json | jq -r '.tables | map(.database) | unique | .[]'

Emit JSON and extract every schema under a specific database:

qyra warehouse-catalog --database jaffle --json | jq -r '.tables | map(.schema) | unique | .[]'

Emit JSON and extract every table under a specific schema:

qyra warehouse-catalog --database jaffle --schema analytics --json | jq -r '.tables[].table'

Emit JSON for a single table's fields (handy for scripts and agents):

qyra warehouse-catalog --database jaffle --schema analytics --table orders --include-fields --json

qyra lint

Validates Qyra Code files (models, charts, dashboards) against JSON schemas. This command checks that your YAML files conform to the expected structure before you deploy.

qyra lint [options]

This command does not support using dbt options.

Options:

• -p, --path <path>
  • Path to a file or directory to lint
  • (default: current directory)
• --verbose
  • (default: false)
  • Show detailed validation output including all validated files
• -f, --format <format>
  • Output format: cli (default) or json (SARIF format)
  • (default: "cli")

Validated file types:

The lint command validates three types of Qyra Code files:

Examples:

Validate all Qyra Code files in the current directory:

qyra lint

Validate a single chart file:

qyra lint --path ./qyra/charts/my-chart.yml

Validate files in a specific directory:

qyra lint --path ./qyra

Show detailed validation output:

qyra lint --verbose

Output results in SARIF JSON format (useful for CI/CD integration):

qyra lint --format json

Errors and warnings:

Lint results are reported at two severities:

• Errors (✗, red) — schema validation failures. The command exits with a non-zero status, failing CI.
• Warnings (⚠, yellow) — non-fatal issues that don't block deployment but signal a configuration likely to behave unexpectedly. Warnings don't change the exit code.

See How to use qyra lint for details.

qyra pre-aggregate-audit

Reports pre-aggregate hit/miss coverage for one dashboard or every dashboard in the project. Use it to find gaps in your pre-aggregate YAML or to gate CI on dashboard coverage.

qyra pre-aggregate-audit [options]

This command does not support using dbt options.

Options:

• --dashboard <uuid-or-slug>
  • Audit a specific dashboard. Required unless --all is set.
• --all
  • Audit every dashboard in the project.
• --project <uuid>
  • Override the active project. Falls back to QYRA_PROJECT_UUID, then to the CLI config.
• --json
  • Emit machine-readable JSON instead of human-friendly text.
• --fail-on-miss
  • Exit 1 if any eligible tile misses. Ineligible tiles do not trigger a failure.
• --verbose
  • Include ineligible tiles (and their reason) in the human output.

See Auditing pre-aggregates from the CLI for the full guide, including miss-reason → YAML-fix mappings and CI examples.

qyra pre-aggregate-check-external

Prints the expected column contract and the exact materialization SQL for each external pre-aggregate, and checks the declared table against that contract. Use it to build the table in the first place, and to catch column drift after a rebuild.

qyra pre-aggregate-check-external [options]

The command runs fully locally. It compiles your dbt project and reads warehouse credentials and dialect from your active profiles.yml target — no Qyra server call is made, so it works before the project is ever deployed.

Options:

• --all
  • Check every external pre-aggregate in the project.
• --json
  • Emit machine-readable JSON instead of human-friendly text. Designed for scripting the table build — wrap each generated SELECT in a CREATE OR REPLACE TABLE.
• --skip-dbt-compile
  • (default: false)
  • Skip dbt compile and read from the existing ./target/manifest.json
• --clear-cache
  • Bypass the warehouse result cache. BigQuery and Snowflake key their caches on query text and can return the pre-rebuild schema without this.
• --fail-on-mismatch
  • Exit 1 on any column drift, so the check can gate CI next to the table build.

See External pre-aggregates for the full workflow, including the column contract, worked invocations, and how average metrics decompose into components.

dbt options

These are options from the dbt Core CLI that also work with some Qyra CLI commands.

dbt node selection

You can select a subset of your dbt models by using the following options on any Qyra commands that support dbt options.

Node selection:

• --select [models...] or -s [models...]
  • Read the dbt docs on select
• --exclude [models...]
  • Read the dbt docs on exclude
• --selector [selector_name]
  • Read the dbt docs on selector

dbt flags

These dbt flags work with Qyra commands that support dbt options. Read the dbt docs on global config flags for details.

• --project-dir [path]
• --profiles-dir [path]
• --profile [name]
• --target [name]
• --no-version-check
• --state [state]
• --full-refresh
• --defer (works with qyra preview and qyra compile)

--defer

--defer is commonly paired with --state and --select state:modified+ to limit a preview to changed models. The behavior below is specific to how Qyra builds the explore list and differs from a plain dbt build --defer.

• --defer only resolves Qyra-joined upstream models against the prod state manifest. It does not promote arbitrary unmodified models from the state manifest into the preview as standalone explores. With --select state:modified+, the preview contains the modified models (compiled to the dev/CI schema), their downstream models, and any models referenced through Qyra join configs (deferred to the prod relations). Standalone tag:qyra models that are not joined to a modified model will not appear. This is the scope of the fix shipped in quanvio/qyra#20672.
• Do not pass --favor-state to preview workflows. --favor-state makes selected nodes prefer the prod relation over the freshly built dev relation, which silently routes the modified model back to stale prod data — the opposite of the intent of a PR preview.
• The comma in dbt's --select is AND, not OR. --select 'tag:qyra,state:modified+' resolves to "modified models that are also tagged qyra", which usually narrows to one or two explores rather than the broader set most users expect. Use space-separated arguments (--select tag:qyra state:modified+) for OR.

dbt project variables

You can set dbt project variables in Qyra commands that support dbt options. Read the dbt docs on project variables for details.

--vars [vars]

dbt threads

You can set the number of threads for dbt in Qyra commands that support dbt options. Read the dbt docs on threads for details.

--threads [number]

Environment Variables

The Qyra CLI supports various environment variables that can be used to configure its behavior. These are especially useful in CI/CD environments where you want to avoid interactive prompts or need to set credentials programmatically.

Core Qyra Configuration

• QYRA_API_KEY

  • API access token for authentication
  • Overrides the API key stored in the config file (~/.config/qyra/config.yaml)
  • Useful for CI/CD pipelines where you don't want to store credentials in files

• QYRA_URL

  • Qyra server URL (e.g., https://app.qyraflow.com)
  • Overrides the server URL in the config file

• QYRA_PROJECT

  • Project UUID to use for CLI commands
  • Overrides the project UUID in the config file
  • Useful when you want to target a specific project without using --project flag

• QYRA_PROXY_AUTHORIZATION

  • Proxy authorization header for proxied access
  • Use this if your Qyra instance is behind a proxy that requires authentication

CI/CD Environment

• CI
  • Set to CI=true to disable interactive prompts and run commands non-interactively in CI/CD environments
  • When enabled, the CLI will:
    • Silence all interactive prompts (including confirmation dialogs)
    • Assume default values or fail if required input is missing
    • Skip certain version checks
    • Adjust behavior for non-interactive execution
  • Automatically detected by most CI/CD platforms (GitHub Actions, GitLab CI, CircleCI, etc.)
  • Usage: Prefix any Qyra command with CI=true to silence prompts:

    CI=true qyra deploy
    CI=true qyra preview
    CI=true qyra generate -s mymodel

dbt Configuration

These environment variables are passed through to dbt and can be used to configure dbt behavior:

• DBT_PROJECT_DIR

  • Directory of dbt project
  • Default: current directory (.)
  • Can also be set using --project-dir flag

• DBT_PROFILES_DIR

  • Directory of dbt profiles
  • Default: ~/.dbt
  • Can also be set using --profiles-dir flag

Environment variables in CI/CD

For a full GitHub Actions workflow that passes these variables as repository secrets, see Automate with CI/CD.