# 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](/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](/cli); to let an agent do the keystrokes, see [Build with agents](/agentic). ## 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. ```mermaid 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](/cli/commands). ## 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 **l**oader **c**onfig: 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](/sdk/api/loader#applications). | | **Environment** | Named variables, request headers and query parameters in `dcupl.lc.json`, applied only to a run that selects them. See [Loader configuration](/console/loader). | | **`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](/cli/workflows). | ## Next steps - [Quickstart](/cli) — Build your first project end to end - [Local data apps](/cli/local-data-apps) — Query your data with the local daemon - [Commands](/cli/commands) — The complete CLI command reference