.md

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 →

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

    ❯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 →

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.

    ❯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 →

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).

    ❯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 →

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.

    ❯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.

    ❯dcupl schemas validate my.workflow-v3.json --against TemplateV3

Local data app

Guide →

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.

    ❯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.

    ❯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.

    ❯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.

    ❯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.

    ❯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.

    ❯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 →

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.

    ❯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 →

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.

    ❯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 →

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).

    ❯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 →

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

  • dcupl validate [flags]

    Validate a project locally or against the cloud.

    ❯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.

    ❯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.