How the CLI works

What is dcupl?

Your agent can write the app. It can't guess your data. Technically, you define models (the shape of your data), load data into them, and query it in memory with facets, aggregations, and filters, in the browser or in Node.js. It ships as a free SDK on npm (@dcupl/core / @dcupl/loader) with an optional cloud (the Console) for versioned storage, workflows, REST API (RAPI) instances and a web UI. See the Introduction for what your agent gets.

The dcupl CLI is the agent's way into all of that, and yours. You use it to scaffold projects, run a local dev server, query your data through an in-memory SDK daemon, validate your models, and sync files with the dcupl cloud — all from your terminal. With --json, the app, validate, workflow, files and schemas commands answer in structured JSON, errors included, and data changes stay staged until one dcupl app build applies them. This page explains the model underneath those commands; if you just want to build something, start with the Quickstart; to let an agent do the keystrokes, see Build with agents.

Mental model

A dcupl project lives in three places at once, and the CLI bridges them:

Workspace — the files on your machine: models, data, loader config, and credentials.
Local app daemon — an in-memory SDK instance the CLI runs on your machine. It loads your workspace (or a Console version, or a URL), you can push data into it directly, and you query it (facets, aggregations, group-bys) from the terminal.
dcupl cloud / Console — versioned file storage and the web UI that operate on the same files as your workspace.

flowchart LR
  subgraph Local["Your Machine"]
    W["Workspace files on disk"]
    A["app daemon (in-memory SDK)"]
  end

  subgraph Cloud["dcupl Cloud"]
    S[Versioned File Storage]
    CN[Console UI]
  end

  U["A URL"]

  W -->|load via dcupl serve| A
  S -->|load a version| A
  U -->|load| A
  W -->|files push / pull| S
  S --- CN

  CLI([dcupl CLI]) -->|query, app data| A
  CLI -.bridges.-> W
  CLI -.bridges.-> S

Add the global --json flag to a command to get machine-readable output for scripting (dcupl serve and dcupl config set print plain text even with it). For the full list of commands, see the Commands reference.

Relationship to the SDK and Console

The SDK (@dcupl/core / @dcupl/loader) is the query engine. When you run dcupl app, the CLI spins up that same engine locally as a daemon, so the queries you run on your machine behave like the ones your application runs on the same SDK version.

The Console is the cloud UI for the same files in your workspace. When you run dcupl files push, you upload your local files to versioned cloud storage that the Console reads and writes. Edit in your editor or in the Console, and keep the two in sync with dcupl files push and dcupl files pull: nothing syncs on its own.

The CLI ships as @dcupl/cli and bundles the @dcupl/core / @dcupl/loader engine. Run dcupl version to see the exact versions you have installed, and compare them with the SDK version your app uses.

Core concepts

A quick glossary of the terms you'll meet across these docs:

Term	What it means
Model	The definition of an entity (its attributes, key, and relations), stored as a `*.dcupl.json` file. Think "the schema of one data type."
Data	The records for a model, stored as `*.data.json` (or loaded from CSV/JSON/NDJSON).
Loader	Reads a `dcupl.lc.json` from a source — your local workspace, a Console version, or a URL — and loads the resources it lists into the SDK.
`dcupl.lc.json`	The loader config: the resources (models, data, scripts, …) that make up the project, plus applications and environments.
Application	A named preset in `dcupl.lc.json`: the resource tags (and variables) a run with that application uses (`default` in the starters loads every resource). See Applications.
Environment	Named variables, request headers and query parameters in `dcupl.lc.json`, applied only to a run that selects them. See Loader configuration.
`dcupl.config.json`	Workspace config at the project root — folder paths and your `projectId`. No secrets.
`dcupl.secrets.json`	Holds your `apiKey`. Never commit it. The `.gitignore` that `dcupl init` writes lists it, but `init --here` leaves an existing `.gitignore` unchanged.
Workspace	Your project files on disk (models, data, config).
Daemon (`dcupl app`)	A live, in-memory SDK instance the CLI runs on your machine. It loads from your workspace, a Console version or a URL, or takes data pushed with `dcupl app data`.
Facet / aggregation / group-by	Query operations: a facet is a value distribution on an attribute; an aggregation computes stats (sum/avg/min/max…); a group-by buckets records by an attribute.
Console	The dcupl cloud: versioned file storage plus the web UI.
Version	A complete, named set of project files in the cloud (e.g. `draft`, `production`).
Runner	A managed cloud environment that executes a deployed workflow.