How the CLI works

What is dcupl?

dcupl is a frontend-first data platform — a TypeScript toolkit for building data-driven apps without waiting on backend infrastructure. You define models (the shape of your data), load data into them, and query it in memory with facets, aggregations, and filters. It ships as an open-source SDK (@dcupl/core / @dcupl/loader) with an optional cloud (the Console) for versioned storage and a web UI.

The dcupl CLI is the command-line entry point to all of that. 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. This page explains the model underneath those commands; if you just want to build something, start with the Quickstart.

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 from your workspace. You load data into it and query it (facets, aggregations, group-bys) without touching the cloud.
  • 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

  W -->|load| A
  A -->|query| W
  W -->|files push / pull| S
  S --- CN

  CLI([dcupl CLI]) -.bridges.-> W
  CLI -.bridges.-> A
  CLI -.bridges.-> S

Add the global --json flag to any command to get machine-readable output for scripting. 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 exactly like the ones your application runs in production.

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 edit in the Console — the files stay in sync through the CLI.

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.

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 A source the SDK reads data from — local files, a remote Console version, or a URL. Loaders are declared in dcupl.lc.json.
dcupl.lc.json The loader config: which models, data, and loaders make up the project, plus environments.
dcupl.config.json Workspace config at the project root — folder paths and your projectId. No secrets.
dcupl.secrets.json Holds your apiKey. Gitignored.
Workspace Your project files on disk (models, data, config).
Daemon (dcupl app) A live, in-memory SDK instance the CLI runs from your workspace, so you can query data locally without the cloud.
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.

Next Steps