Data apps are usually built by prompting the agent in the Qyra UI, but every app is ultimately a small React project — and you can work on that project directly. The CLI lets you:

• Download an app's source, check it into git, and review changes in pull requests.
• Edit the app in your own editor, or point your own AI coding agent at it.
• Preview the app locally against real Qyra data, with your permissions.
• Upload your changes — the server rebuilds the app and publishes a new version.
• Create brand-new apps from scratch, without going through the UI at all.
• Move apps between projects and instances.

Custom chart types share this folder layout and build pipeline but are a separate as-code resource: they live in qyra/chart-types/ and move with the --chart-types flags instead of --apps. See Chart types as code.

Prerequisites

• The Qyra CLI installed and logged in (qyra login <your-instance-url>), version 1.55.0 or later.
• Data apps enabled on the instance (enterprise).
• An Editor role or above on the project — uploading requires the create:DataApp scope. Non-Editors can be granted create:DataApp@preview instead to upload only to preview projects they created themselves; see Restrict data app uploads to previews.
• Node.js 20+ (which includes npm) for local builds, previews, and qyra apps create.

Quickstart: download, edit, upload

This ten-minute loop is the core workflow. It assumes you already have an app in your project (built in the UI); to start from nothing instead, skip ahead to Creating a new app locally.

1. Download the app

Apps are identified by their slug — a project-scoped id derived from the app's name. You can pass a slug, a UUID, or simply paste the app's URL:

qyra download --apps-only --apps revenue-explorer

--apps-only gives you a clean, app-only checkout — no charts, dashboards, or space files. The app lands in qyra/apps/revenue-explorer/.

2. Look around

Every downloaded app is a locally buildable Vite + React project:

The built output (dist/) is intentionally never downloaded or uploaded — the server always rebuilds from source.

3. Make a change

Edit anything under src/. If you're using an AI coding agent, point it at the app folder — the bundled AGENTS.md and .claude/skills/ teach it the ground rules, and .qyra/context/semantic-layer.yml tells it which fields exist.

To sanity-check that the source still compiles:

npm install
npm run build

To catch manifest, dependency, and semantic-layer reference issues before uploading, run:

qyra apps validate

This checks the app's qyra-app.yml, pnpm-lock.yaml, external connection aliases, and the fields your code references against the local .qyra/context/ snapshot. Add --live to check against fresh explores from the project instead. See qyra apps validate for the full flag list.

4. Preview it against real data (optional)

qyra apps preview

Run this from inside the app folder (or pass the folder as an argument). It starts the Vite dev server with a local proxy that lets the app run real queries against your Qyra instance — authenticated as you, with your permissions and user attributes. Open the URL Vite prints (usually http://localhost:5173) and edit src/ with instant hot reload.

See Local preview for details and limitations.

5. Upload

qyra upload --apps revenue-explorer

The CLI posts the src/ tree and manifest, then returns immediately:

Uploaded "Revenue explorer" — updated v4 (…). Building in the background;
the app will show "building" until the server finishes.

The server rebuilds the app in its sandbox and publishes the new version once the build succeeds. If the build fails, the error shows up in the app's version history in the UI.

That's the whole loop: edit src/, upload, repeat.

Creating a new app locally

You don't need the UI to start an app. qyra apps create scaffolds a complete, buildable app folder:

qyra apps create "Revenue explorer"
# creates ./qyra/apps/revenue-explorer

The command:

1. Checks the slug is available in the target project (derived from the name; override with --slug).
2. Asks for confirmation, then installs the template's npm packages and generates the shadcn UI components locally (this is why npm is required). Pass -y to skip the prompts in scripts.
3. Writes a ready-to-edit app folder with the same layout as a downloaded app, including the .qyra/context/ snapshot of your project's semantic layer.

The app doesn't exist on the server yet — it's created on your first upload:

cd qyra/apps/revenue-explorer
npm run build          # optional local check
qyra upload --apps revenue-explorer

Useful flags: --description <text>, --slug <slug>, --project <uuid> (defaults to your selected project), -p, --path <path> (content root, default ./qyra).

Understanding identity: slugs

The slug field in qyra-app.yml is the app's identity, and it's scoped to a project — the same slug can exist in different projects. On upload, the server upserts by slug in the target project:

• Slug exists there → a new version is appended to that app.
• Slug doesn't exist there → a new app is created with that slug.

This makes app folders portable: the same folder can update the app in project A and create/update a sibling in project B, with no manifest editing in between. The folder name matches the slug by convention, but the manifest is what counts.

Renaming an app is a metadata edit: change name (or description) in the manifest and upload. The slug — and therefore the app's identity and URLs — doesn't change.

Copying an app instead of updating it

Pass --create-new to force a fresh app (with a newly generated slug) instead of updating the one the manifest points at — useful for forking:

qyra upload --apps revenue-explorer --create-new

Moving apps between projects and instances

Between projects on one instance, target the other project:

qyra upload --apps revenue-explorer --project <target-project-uuid>

Between instances, log in to the destination first (or set QYRA_URL and QYRA_API_KEY):

qyra login https://destination.qyraflow.com
qyra upload --apps revenue-explorer --project <target-project-uuid>

The destination rebuilds the source in its own sandbox — no built artifacts move between instances.

Pass --app-space <spaceRef> (slug or space UUID) to land any new apps this upload creates in a specific space. Existing apps keep their space, so this flag only affects the first upload of an app to a project:

qyra upload --apps revenue-explorer --project <target-project-uuid> --app-space finance

Versioning

Every accepted upload creates a new version of the app, alongside versions created by prompting in the UI. Versions move through pending → building → ready (or error), and viewers always see the latest ready version. The full timeline — including who created each version and any build errors — is in the app's version history in the UI, where you can also restore an earlier version.

Two behaviors keep the version history clean:

• Unchanged uploads are skipped. If the source, dependencies, and viz schema are byte-for-byte identical to the latest version, the server skips the rebuild and reports matches v<n> — skipped, no rebuild. Name/description edits still apply. Pass --force to rebuild anyway. (A latest version in error state is never skipped — re-uploading retries the build.)
• Build slots are limited. Each project runs at most 5 app builds at once. If you upload a large batch, the CLI automatically waits for a free slot (up to 10 minutes of consecutive waiting) instead of failing — you'll see Project build limit reached — waiting for builds to finish….

For CI, note that qyra upload exits non-zero if any app upload fails, and prints a per-run tally: data apps created / updated / unchanged / failed / skipped.

We recommend treating git as the source of truth for locally-managed apps: commit the app folder, make changes via PRs, and upload from CI or after merge. Re-download after someone iterates on the app in the UI, so your local copy doesn't silently drift behind.

Data apps on dashboards

Dashboards reference data app tiles portably, by appSlug in the dashboard YAML. The CLI keeps the two in sync:

• qyra download (with dashboards) also downloads any data apps the dashboards reference, into qyra/apps/.
• qyra upload (with dashboards) uploads referenced app folders before the dashboards — even without any --apps flag — so the tiles resolve. Unchanged apps that already exist in the target are skipped.

If a dashboard tile references an app that has no local folder and doesn't exist in the target project, the tile is skipped with a warning rather than failing the dashboard upload.

Local preview

qyra apps preview runs a downloaded (or locally created) app on your machine against a real Qyra instance:

cd qyra/apps/revenue-explorer
npm install            # preview does not auto-install
qyra apps preview

Open the URL the Vite dev server prints (usually http://localhost:5173). Edits to src/ hot-reload instantly, and every query the app runs goes to your real project.

How authentication works. Your API key never reaches the app or the browser. The CLI starts a loopback proxy that holds your credential; the dev server forwards the app's API calls through it. The proxy only allows the same narrow set of SDK routes a deployed app can reach (running queries, polling results, downloads), pins requests to one project, and strips cookies in both directions. A bare npm run dev without the CLI has no data access at all.

Things to know:

• You see your own data. Preview runs with your permissions and user attributes. Viewers of the deployed app may see different results.
• Pick the project with --project <uuid> (defaults to the manifest's project) and override credentials with --url / --token (prefer qyra login or QYRA_API_KEY over --token, which leaks into shell history).
• Not everything is emulated. External connection fetches, Google Sheets export, the network inspector, data-app-viz field context, and URL state integration only work in the deployed app.
• Apps downloaded with an older CLI may predate the preview proxy — re-download the app if preview tells you the scaffolding is too old.

External connections

If an app fetches from third-party APIs via external connections, the manifest records the links:

externalConnections:
  - alias: stripe            # the name the app code uses
    connectionSlug: stripe-api  # the connection registered in the project

On upload, each connectionSlug is resolved in the target project:

• If the field is present, the app's links are reconciled to match it exactly (an empty list [] unlinks everything).
• If the field is absent, existing links are left untouched.
• A slug that doesn't exist in the target is skipped with a warning — the app still uploads, but that fetch will fail at runtime until the connection is linked.

The connection definitions themselves are a separate as-code resource. To move an app and its connections to a new project:

# In the source project
qyra download --include-external-connections --apps-only --apps revenue-explorer

# In the target project (secrets never travel in files — provide them via env)
export QYRA_EXTERNAL_CONNECTION_SECRET_STRIPE_API=sk_live_…
qyra upload --apps revenue-explorer --project <target-project-uuid>

Connection files live in qyra/external-connections/<slug>.yml and upload before apps in the same run, so the links resolve. Managing connections requires the admin-only manage:ExternalConnection scope.

Advanced: how the build works

You never upload compiled output — the server builds every version from source in an isolated sandbox:

1. qyra upload posts the manifest and the src/ tree. The server validates the bundle, stores the source, and creates a new version in pending.
2. A build job restores the source into a sandbox containing the trusted app template. Any scripts in an uploaded package.json are replaced with the template's — the build command is never uploader-controlled.
3. The sandbox runs the standard Vite production build. There's no AI involved and no auto-fixing: the build either succeeds or fails loudly.
4. On success the compiled app is published and the version becomes ready. On failure the version is marked error with the compiler output attached in the version history.

Because the server rebuild is authoritative, your local npm run build is only a convenience pre-check — a local failure (from a Node version mismatch, say) doesn't predict a server failure, which is why the CLI treats it as a warning.

Limits: 5 concurrent builds per project (the CLI waits for a slot automatically), 60 direct custom dependencies, 2 MB lockfile.

Experimental: custom dependencies

By default, apps build against a fixed, pre-installed library set — edits to package.json are ignored. With custom dependencies enabled, you can extend that set from the app folder:

cd qyra/apps/revenue-explorer
pnpm add deck.gl          # updates package.json AND pnpm-lock.yaml
qyra upload --apps revenue-explorer

Both files matter: the dependency set is package.json plus a matching pnpm-lock.yaml (the server installs with pnpm, so an npm lockfile won't do). On upload, the CLI shows what you're adding and asks for confirmation:

"revenue-explorer" declares custom dependencies that will be installed in the build sandbox:
  + deck.gl@^9.3.5 (not in default template)
Upload "revenue-explorer" with custom dependencies?

Rules the CLI and server enforce:

• Registry semver specs only (^9.3.5, ~1.2.0, ranges). No git:/file:/URL specs and no dist-tags like latest.
• At most 60 direct dependencies; lockfile ≤ 2 MB and consistent with package.json.
• Every version is screened against the OSV malicious-package feed at upload; known-bad versions are rejected outright.

Security model: the sandbox installs with --frozen-lockfile --ignore-scripts, with network egress limited to the npm registry, and the build never sees any credentials. Install scripts also never run on your machine — the scaffolded .npmrc sets ignore-scripts=true; keep it. Self-hosted instances can additionally require a minimum package release age (QYRA_APP_DEPENDENCY_MIN_RELEASE_AGE_DAYS) or point installs at an internal mirror (QYRA_APP_DEPENDENCY_REGISTRY_HOSTS).

Uploads are the only way to change dependencies. When someone iterates on the app in the UI, the AI builder can edit src/ but the stored dependency set is restored as-is — its package.json edits are ignored. Dependency changes on a version are visible in the version history.

CLI reference

See qyra apps create, qyra apps preview, qyra apps validate, and the data app flags on qyra download and qyra upload for the full flag lists.