CLI

Commands Reference

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

--json is a global flag available on every command. It switches output to machine-readable JSON for scripting and automation.

⌕

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 --name "My App" --starter minimal
6 flags
--name <str> Project name.
--here Scaffold into the current directory instead of a new one.
--starter <minimal|empty|existing> Choose the starter template.
--project-id <str> For existing: the cloud project ID to link.
--api-key <str> For existing: API key for the linked project.
--console-api-url <str> For existing: override the console API URL.

Dev server

Guide →

Serve a project locally for development.

  • dcupl serve [path]

    Start the dev server for the project at path.

    ❯dcupl serve --port 9000 --open-browser
  • dcupl serve list

    List running dev servers.

  • dcupl serve stop --port <n>

    Stop the dev server on the given port.

2 flags
--port <n> Port to serve on (default 8083).
--open-browser Open the served app in your browser.

Code generation

Guide →

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

  • dcupl generate [type]

    Generate a file of the given type.

    ❯dcupl generate typescript --from data/products.json --name Product
7 flags
--name <str> Name of the generated artifact.
--file-name <str> Override the output file name.
--from <file> Generate from an existing source file.
--register Register the generated artifact in the relevant config.
--key-property <str> Key property to use for the model.
--sample-size <n> Number of rows to sample when inferring from data.
--dry-run Print the result 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 sample payload.

    ❯dcupl schemas get ModelDefinition --example

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 --model <str> [--file|--content]

    Set a model definition.

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

  • 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 '{"price":{"$gt":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 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.

32 flags
--auto-update create Re-process loaders automatically on change.
--auto-generate-properties create Auto-generate model properties from data.
--auto-generate-deep create Deep auto-generation of nested properties.
--auto-generate-sample-size <n> create Rows to sample during auto-generation.
--quality <bool> create Enable/disable data quality checks.
--cache create Enable caching.
--clone create Clone an existing app's configuration.
--analytics create Enable analytics.
--logging-level <level> create Logging verbosity.
--max-memory <MB> create Memory ceiling in MB.
--idle-timeout <min> create Shut down after min minutes idle.
--load create Process loaders on startup.
--lc-json <path> create Path to a dcupl.lc.json config.
--auto-serve create Serve the app automatically after create.
--auto-serve-port <n|auto> create Port for auto-serve (auto to pick one).
--file <path> data Read data from a file.
--url <url> data Read data from a URL.
--content <str> data Inline content (- for stdin).
--format <csv|json|ndjson> data Input data format.
--model <str> data, query, fn Target model.
--key-property <str> data Key property; composite as a,b,c.
--auto-generate-key data Generate item keys automatically.
--query <str> query, fn Inline query / restrict to matching items.
--query-file <path> query Read query from a file.
--sort <field:asc|desc> query, groupBy Sort results by field.
--sort <size-desc|size-asc|value-asc|value-desc> fn facets Facet sort order (fixed enum, not field:dir).
--limit <n> query, fn Maximum results / limit facet values.
--start <n> query 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.

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

    Copy a version.

  • dcupl files versions delete <id>

    Delete a version.

5 flags
--version <str> Target version.
--strict Mirror the source, including deletions. Default (additive) never deletes.
--yes Skip confirmation prompts.
--force Resolve conflicts by overwriting the other side.
--path <str> Limit to a path (repeatable).

Credentials

Guide →

Configure and inspect stored credentials.

  • dcupl config set [flags]

    Set credential values.

    ❯dcupl config set --project-id my-project --api-key $DCUPL_API_KEY
  • 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 Skip confirmation prompts.

Workflows (v3)

Guide →

Validate, deploy, and trace v3 workflows.

  • dcupl workflow validate

    Validate a workflow template.

  • dcupl workflow deploy

    Deploy a workflow to a runner.

    ❯dcupl workflow deploy --file my.workflow-v3.json --runner default --wait
  • dcupl workflow undeploy

    Remove a deployed workflow.

  • dcupl workflow test

    Test-run a workflow.

  • dcupl workflow list

    List workflows.

  • dcupl workflow get

    Get a workflow.

  • dcupl workflow template

    Print a workflow template.

  • dcupl workflow status

    Show deployment status.

  • dcupl workflow history

    Show run history.

  • dcupl workflow trace --id <str> --run <str>

    Trace a specific run.

  • dcupl workflow runners list

    List runners.

  • dcupl workflow runners get --id <str>

    Get a runner.

6 flags
--file <path> deploy, test Workflow template file.
--runner <str> deploy, test Target runner.
--wait deploy, test Wait for completion.
--swap-timeout <ms> deploy, test Timeout for hot-swap.
--id <str> trace, runners get Workflow/runner ID.
--run <str> trace Run ID to trace.

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
9 flags
--source <local|remote> Validation source.
--lc-json <path> Path to a dcupl.lc.json config.
--project-id <str> Cloud project ID.
--api-key <str> Cloud API key.
--version <str> Project version.
--app-key <str> App key.
--env <str> Environment.
--quality <bool> Toggle quality checks.
--limit <n> Limit items validated.

Utility

Version and diagnostic helpers.

  • dcupl version

    Print the CLI version and resolved @dcupl/* package versions.

    ❯dcupl version