# Commands reference

Every command family the `dcupl` binary exposes — search by command or description, filter by family, and copy any signature.

The flag tables cover the flags you'll use most. `dcupl <command> --help` lists every flag a command takes and is the complete reference.

> **Note:** `--json` is a **global flag** available on every command. It switches output to machine-readable JSON for scripting and automation: one JSON value per result on stdout (`app create --load` prints one per step); an error is `{ "success": false, "error": "…", "code": "…" }` on stdout with exit code 1. `files push` and `files pull` with failed or unverified transfers print their summary with `"success": false` instead and exit 2. `dcupl serve` and `dcupl config set` print plain text even with `--json`.

## Project setup

[Guide](/cli/scaffolding)

Scaffold a new dcupl project or wire an existing one into your workspace.

- `dcupl init [target]`

  Create a new project in target (defaults to a new directory). · alias `dcupl new`

  ```bash
  dcupl init my-app --starter minimal
  ```

**6 flags**

- `--name <str>` — Folder to create, same as \[target\] (wins over it).
- `--here` — Scaffold into the current directory instead of a new one.
- `--starter <minimal|empty|existing>` — Choose the starter template. Without it (and without --json or --project-id), init prompts for the starter, which needs a terminal.
- `--project-id <str>` — For existing: the cloud project ID to link. Implies --starter existing (any other starter is refused). Without --starter or --json, init stays interactive: it asks for the folder name (unless --here) and for the project ID and key when --api-key is missing or fails validation, so pass --starter existing in scripts and CI.
- `--api-key <str>` — For existing: API key for the linked project.
- `--console-api-url <str>` — For existing: override the console API URL. Hidden: dcupl init --help does not list it.

## Dev server

[Guide](/cli/local-data-apps)

Serve a project locally for development.

- `dcupl serve [path]`

  Start the dev server for the workspace folder at path (default dcupl). Listens on 127.0.0.1 only and answers pages on this machine and the dcupl Console. File edits need the per-session token printed at startup (x-dcupl-serve-token header), except from the dcupl Console or an --allow-origin origin on this machine.

  ```bash
  dcupl serve --port 9000 --no-open-browser
  ```

- `dcupl serve list`

  List running dev servers.

- `dcupl serve stop --port <n>`

  Stop the dev server on the given port.

**4 flags**

- `--port <n>` — Port to serve on (default 8083).
- `--open-browser / --no-open-browser` — Open the welcome screen in your browser on start (default on; overrides openBrowser in dcupl.config.json).
- `--host [address]` — Address to listen on (default 127.0.0.1, this machine only). A bare --host listens on all interfaces (0.0.0.0). File edits from other machines need the printed token.
- `--allow-origin <origin>` — Let another browser origin read files and, from this machine, edit them without the token, like the dcupl Console (repeatable). Example: https://console.example.com for a self-hosted Console.

## Code generation

[Guide](/cli/scaffolding)

Generate models, types, schemas, transformers, scripts, operators, tests, workflow templates, and REST API templates. Supported types: model, typescript, json-schema, transformer, script, operator, test, test-setup, test-config, workflow, api.

- `dcupl generate [type]`

  Generate a file of the given type. A missing required flag is prompted for (needs a terminal).

  ```bash
  dcupl generate model --from dcupl/data/products.csv --name Product --register
  ```

**14 flags**

- `--name <str>` — model: the model key. workflow: the workflow key. api: the REST API template key.
- `--file-name <str>` — Output file name. Required for transformer, script, typescript, json-schema, test, and test-config.
- `--operator <name>` — operator: the operator name (writes <name>.operator.js).
- `--mode <endpoint|script|operator|sort>` — script: the starter to write (default operator).
- `--endpoint "<GET|POST> <path>=<scriptKey>"` — api: a scripted endpoint (repeatable).
- `--template <preset>` — workflow: the preset (default read-transform-write).
- `--force` — api, script: overwrite a file that already exists (by default it is kept and reported as skipped). For api this writes a new auth key and drops endpoints added by hand; endpoint scripts are never overwritten.
- `--title <str>` — test: the test title.
- `--from <file>` — model: infer the model from a CSV, JSON, or NDJSON file.
- `--delimiter <d>` — model --from: the CSV column delimiter (, ; tab or |, also comma, semicolon, tab, pipe). Detected from the header and the first 50 rows by default; the command fails with GENERATE\_NO\_DELIMITER when no delimiter fits, and --register writes it into the data resource as options.csvParserOptions.delimiter.
- `--register` — model --from: add the model + data resource to dcupl.lc.json. model (without --from), transformer, script, and operator are always registered.
- `--key-property <str>` — model --from: override the inferred key (comma-separate for a composite key).
- `--sample-size <n>` — model --from: max rows to scan when inferring types (default: every row). Zero-padded digit codes such as 00123 are inferred as string.
- `--dry-run` — model --from: print the proposed model without writing files.

## Schemas

[Guide](/cli/schemas)

Inspect the built-in dcupl schemas.

- `dcupl schemas list`

  List all built-in schemas.

- `dcupl schemas get <name> [--example]`

  Print a schema's source; --example appends a curated example payload for the schemas that ship one.

  ```bash
  dcupl schemas get ModelDefinition --example
  ```

- `dcupl schemas validate <file> --against <name>`

  Validate a JSON file against a \[Zod\] schema such as TemplateV3; exits 1 when it is invalid.

  ```bash
  dcupl schemas validate my.workflow-v3.json --against TemplateV3
  ```

## Local data app

[Guide](/cli/local-data-apps)

Manage a long-running local data app daemon: lifecycle, models, data, queries, functions, and loaders.

- `dcupl app create`

  Create and start a new local data app.

  ```bash
  dcupl app create --lc-json dcupl.lc.json --load --auto-serve
  ```

- `dcupl app destroy [--app <id>] [--keep-logs]`

  Destroy an app; optionally keep its logs.

- `dcupl app list`

  List local data apps.

- `dcupl app status [--app <id>]`

  Show app status.

- `dcupl app build [--app <id>]`

  Build the app — apply staged changes.

- `dcupl app logs [--app <id>] [--lines <n>]`

  Tail the last n log lines.

- `dcupl app models keys`

  List model keys.

- `dcupl app models get --model <str>`

  Get a model definition.

  ```bash
  dcupl app models get --model Product
  ```

- `dcupl app models set [--file|--content]`

  Set a model definition (the model key comes from the definition's key).

- `dcupl app models remove --model <str>`

  Remove a model.

- `dcupl app data upsert`

  Insert or update items.

  ```bash
  cat products.csv | dcupl app data upsert --model Product --content=- --format csv
  ```

- `dcupl app data update`

  Update existing items (rows with an unknown key are skipped).

- `dcupl app data set`

  Replace items.

- `dcupl app data remove`

  Remove items.

- `dcupl app data reset`

  Reset a model's data.

- `dcupl app query one --model <str> --item-key <str>`

  Fetch a single item by key.

- `dcupl app query execute --model <str> [flags]`

  Run a query against a model.

  ```bash
  dcupl app query execute --model Product --query '{"attribute":"price","operator":"gt","value":100}' --sort price:desc --limit 20
  ```

- `dcupl app fn facets --model <str> --attribute <str>`

  Compute facets for an attribute.

  ```bash
  dcupl app fn facets --model Product --attribute category --sort size-desc --limit 10
  ```

- `dcupl app fn aggregate --model <str> --attribute <str> --types <list>`

  Aggregate an attribute.

- `dcupl app fn groupBy --model <str> --attribute <str>`

  Group items by an attribute.

- `dcupl app fn metadata --model <str>`

  Return model metadata.

- `dcupl app fn pivot --model <str> --rows <attr> --columns <attr> --values <attr>:<type>`

  Cross-tab rows x columns x values (or pass a full PivotOptions JSON with --spec).

- `dcupl app fn suggest --model <str> --attribute <str> --value <str>`

  Typeahead suggestions for an attribute value.

- `dcupl app loaders add --key <str> [--source local|remote|url]`

  Add a loader.

  ```bash
  dcupl app loaders add --key products --source local
  ```

- `dcupl app loaders process [flags]`

  Process loaders.

- `dcupl app loaders list`

  List loaders.

- `dcupl app loaders get [--loader <key>]`

  Get a loader config.

- `dcupl app loaders remove [--loader <key>]`

  Remove a loader. The app is marked dirty (and built right away with --auto-update), so the next build drops the models and data the loader loaded; the command warns about pending changes.

**34 flags**

- `--app <id>` — all — App id. create: auto-generated if omitted. Other commands: optional when exactly one app is running.
- `--auto-update` — create — Run update() after every mutation. Default off: mutations are staged until dcupl app build.
- `--auto-generate-properties` — create, data — Infer model properties from the data: the first row names the columns and their types, and a column it types as a number is checked against every row (a later decimal makes it float, a zero-padded code such as 00123 makes it string). See --auto-generate-deep to reconcile every column. On a data verb it overrides the daemon default for that call.
- `--auto-generate-deep` — create, data — Infer the model from every row, reconciling the types of every column across rows (blank cells are ignored). Implies --auto-generate-properties.
- `--auto-generate-sample-size <n>` — create, data — Infer the model from at most the first n rows. Implies --auto-generate-deep.
- `--quality <bool>` — create — Enable/disable data quality checks.
- `--cache` — create — Cache query, facet and aggregation results until the data changes, the SDK's performance.cache option (default true; --no-cache turns it off).
- `--clone` — create — Deep-clone data to avoid mutation side effects (default false).
- `--logging-level <level>` — create — Logging verbosity.
- `--max-memory <MB>` — create — Memory ceiling in MB.
- `--idle-timeout <min>` — create — Shut down after min minutes idle (default 30).
- `--load` — create — Process loaders on startup.
- `--lc-json <path>` — create — Path to a dcupl.lc.json config.
- `--auto-serve` — create (--load), loaders add — Start dcupl serve for the workspace source if it is not running.
- `--auto-serve-port <n|auto>` — create (--load), loaders add — Port for auto-serve (auto to pick one).
- `--cdn-base-url <url>` — create, loaders add — CDN host for a remote (Console) source. Defaults to the dcupl CDN, also when consoleApiUrl points at a self-hosted Console, so set it (or DCUPL\_CDN\_BASE\_URL, or cdnBaseUrl in dcupl.config.json) for a self-hosted Console.
- `--file <path>` — data — Read data from a file. The CSV delimiter (, ; tab or |) is detected.
- `--url <url>` — data — Read data from a URL.
- `--content <str>` — data, models set — Inline content. --content=- reads stdin (the spaced form --content - is rejected).
- `--format <csv|json|ndjson>` — data — Input data format.
- `--model <str>` — data, query, fn — Target model.
- `--key-property <str>` — data — Key property. Comma-separate for a composite key: a,b builds the key "a::b" (the keyProperty array of the SDK), as generate model --key-property does.
- `--auto-generate-key` — data — Generate item keys automatically.
- `--query <str>` — query, fn — Inline query / restrict to matching items.
- `--query-file <path>` — query, fn — Read query from a file.
- `--sort <field:asc|desc>` — query — Sort results by field. A direction other than ASC or DESC fails with PARSE\_ERROR.
- `--sort <key|size|attr_type>[:ASC|DESC]` — fn groupBy — Order the groups by key, size or a requested --aggregate (e.g. price\_avg:DESC); --limit/--start apply after sorting. A model attribute orders the items inside each group instead.
- `--sort <size-desc|size-asc|value-asc|value-desc>` — fn facets — Facet sort order (fixed enum, not field:dir).
- `--limit <n>` — query execute, fn facets, fn groupBy — Maximum results / limit facet values.
- `--start <n>` — query execute, fn groupBy — Offset for pagination.
- `--projection <str>` — query — Fields to project.
- `--types <distinct,count,sum,avg,min,max,group>` — fn aggregate — Aggregation types to compute.
- `--aggregate <attr>:<type[,type...]>` — fn groupBy — Per-group aggregates, e.g. price:avg. Repeat to combine.
- `--loader <key>` — loaders — Target loader key.

## Cloud sync

[Guide](/cli/cloud-sync)

Sync project files with the dcupl cloud.

- `dcupl files status [--version]`

  Show local vs. remote diff.

- `dcupl files push [flags]`

  Push local files to the cloud.

  ```bash
  dcupl files push --version main --yes
  ```

- `dcupl files pull [flags]`

  Pull cloud files locally.

- `dcupl files list [--version] [--search] [--tree]`

  List remote files.

- `dcupl files read --path <str>`

  Read a remote file.

- `dcupl files write --path <str> [--content|--file]`

  Write a remote file.

- `dcupl files delete --path <str> [--yes] [--dry-run]`

  Delete a remote file.

- `dcupl files move --from <str> --to <str>`

  Move/rename a remote file.

- `dcupl files copy --from <str> --to <str>`

  Copy a remote file.

- `dcupl files create-folder --path <str>`

  Create a remote folder.

- `dcupl files versions list`

  List versions (also what dcupl files versions runs without a verb).

- `dcupl files versions copy --from <str> --to <str>`

  Copy a version.

- `dcupl files versions delete <id>`

  Delete a version.

**8 flags**

- `--version <str>` — Target version, alias -v (default: HEAD, then draft). push rejects production.
- `--strict` — push/pull only: also mirror deletions since the last sync (push deletes a server file you deleted locally, pull deletes a local file that was deleted on the server; if the other side changed the file, it is a conflict instead). Without a sync baseline nothing is deleted. Default (additive) never deletes.
- `--yes` — Skip confirmation prompts.
- `--force` — push/pull only: resolve conflicts by overwriting the other side.
- `--path <str>` — status/push/pull: limit to files, folders, or globs (repeatable). read/write/delete/create-folder: the remote path (required).
- `--dest <path>` — pull only: write the pulled files here instead of the workspace (no sync state, no conflict checks).
- `--dry-run` — delete, move, versions copy/delete: preview without executing.
- `--concurrency <n>` — push/pull only: max parallel file transfers (default 4). Lower it for very large files or slow links.

## Credentials

[Guide](/cli/cloud-sync)

Configure and inspect stored credentials.

- `dcupl config set [flags]`

  Write projectId to dcupl.config.json and apiKey to dcupl.secrets.json (to .env as DCUPL\_API\_KEY when there is no secrets file). Prints plain text even with --json.

  ```bash
  dcupl config set --project-id my-project --api-key "$DCUPL_API_KEY" --yes
  ```

- `dcupl config get [--show-secrets]`

  Show the current config; reveal secrets with --show-secrets.

**4 flags**

- `--project-id <str>` — Set the project ID.
- `--api-key <str>` — Set the API key.
- `--console-api-url <str>` — Set the console API URL.
- `--yes` — Never prompt; needs --project-id and --api-key (or values already in the files). Also the behavior when stdin is not a terminal.

## Workflows

[Guide](/cli/workflows)

Validate, deploy, and trace workflows.

- `dcupl workflow validate --file <path> [--runner <str>] [--local-only]`

  Validate a template locally, and remotely when --runner is given.

- `dcupl workflow deploy --file <path> --runner <str>`

  Validate remotely, then deploy to a runner (asks to confirm unless --yes).

  ```bash
  dcupl workflow deploy --file my.workflow-v3.json --runner default --yes
  ```

- `dcupl workflow undeploy --id <str>`

  Remove a deployed workflow.

- `dcupl workflow test --file <path> --runner <str>`

  Deploy to a (dev) runner, then run it: one node with --node, otherwise a full run.

- `dcupl workflow run <key> --runner <str>`

  Trigger an already-deployed workflow without redeploying.

- `dcupl workflow list`

  List workflows.

- `dcupl workflow get --id <str>`

  Get a workflow.

- `dcupl workflow template --id <str>`

  Print the template running on the runner (drift check).

- `dcupl workflow status --id <str>`

  Show deployment status.

- `dcupl workflow history --id <str>`

  Show run history.

- `dcupl workflow trace --id <str> [--run <str>|--last]`

  Trace a specific run, or the most recent one with --last.

- `dcupl workflow runners list`

  List runners (also what dcupl workflow runners runs without a verb).

- `dcupl workflow runners get --id <str>`

  Get a runner.

**10 flags**

- `--file <path>` — validate, deploy, test — Workflow template file.
- `--runner <str>` — validate, deploy, test, run — Runner uid or runnerKey.
- `--local-only` — validate — Skip remote validation even if --runner is set (default false).
- `--yes` — deploy, undeploy — Skip the confirmation prompt (for CI).
- `--wait` — deploy, test — Wait for the runner to hot-swap to the new version. On by default; --no-wait skips it.
- `--swap-timeout <ms>` — deploy, test — Max ms to wait for the hot-swap (default 30000).
- `--node <id>` — test, run — Run a single node instead of the whole workflow.
- `--id <str>` — get, template, status, history, trace, undeploy, runners get — Deployed workflow uid (runners get: runner uid).
- `--run <str>` — trace — Run ID to trace (from workflow history).
- `--last` — trace — Trace the most recent run.

## Validation

[Guide](/cli/validate)

Validate a project's data and configuration, locally or against the cloud.

- `dcupl validate [flags]`

  Validate a project locally or against the cloud.

  ```bash
  dcupl validate --source local --lc-json dcupl.lc.json
  ```

**11 flags**

- `--source <local|remote>` — Validation source.
- `--cdn-base-url <url>` — CDN host for --source remote. Defaults to the dcupl CDN, also when consoleApiUrl points at a self-hosted Console, so set it (or DCUPL\_CDN\_BASE\_URL, or cdnBaseUrl in dcupl.config.json) for a self-hosted Console.
- `--lc-json <path>` — Path to a dcupl.lc.json config.
- `--no-auto-serve` — Local source: do not start the throwaway dcupl serve that validate starts by default.
- `--project-id <str>` — Cloud project ID.
- `--api-key <str>` — Cloud API key.
- `--version <str>` — Project version (remote source, default draft).
- `--app-key <str>` — App key.
- `--env <str>` — Environment key (repeatable).
- `--quality <bool>` — Toggle quality checks (default true).
- `--limit <n>` — Max error records in the report (default 10).

## Utility

Version and diagnostic helpers.

- `dcupl version`

  Print the CLI version and resolved @dcupl/\* package versions, plus a notice when npm has a newer version on your channel. dcupl --version does the same.

  ```bash
  dcupl version
  ```

## Deprecated

The file commands from CLI 1.3 still run, with a deprecation notice. Use the replacement instead.

- `dcupl files:push`

  Legacy upload that sends only .csv, .json and .js files and skips every other file. Use dcupl files push.

- `dcupl files:pull`

  Legacy download. Use dcupl files pull.

- `dcupl files:copy --from <id> --to <id>`

  Copies a version without asking. Use dcupl files versions copy.

- `dcupl files:versions`

  Lists versions. Use dcupl files versions list.

## Next steps

- [Local data apps](/cli/local-data-apps) — Run the daemon, query data, run functions
- [Cloud Sync](/cli/cloud-sync) — Push, pull, and version project files
- [Workflows](/cli/workflows) — Validate, deploy, and trace workflows
- [Schemas](/cli/schemas) — Discover exact field names for any config