CLI

Cloud Sync & Configuration

Connect your local workspace to a dcupl Console project, then keep the two in sync. The CLI tracks what changed on each side and transfers only the differences — pushes and pulls stay fast, predictable, and never silently clobber edits made on the other side.

Do this first. Every files command needs a project ID and API key. Create a project in the dcupl Console to get them, then run dcupl config set once — see Configure credentials below. Without it, the commands on this page will fail with an auth error.

How sync works

Sync is a 3-way diff: the CLI compares your local files, the server, and the last-synced baseline to decide what to push, pull, or flag as a conflict. Toggle the mode to see how deletions are handled.

Additive: only new and changed files transfer — nothing is ever deleted.

File	Local	Server	Action
`models/Product.dcupl.json`	modified	unchanged	Push
`workflows/sync.workflow-v3.json`	added	absent	Push (new)
`models/Order.dcupl.json`	unchanged	modified	Pull
`data/products.csv`	modified	modified	Conflict — stops
`data/legacy.csv`	deleted	present	Kept on server

The status → review → push loop

files status is read-only — it transfers nothing. Review the diff, then push.

zsh — cloud sync

# see what differs between local and server — read-only

❯dcupl files status --json

{
  "push":     ["models/Product.dcupl.json", "workflows/sync.workflow-v3.json"],
  "pull":     ["models/Order.dcupl.json"],
  "conflicts": ["data/products.csv"]
}

# a conflict stops the push — resolve it by choosing a winner

❯dcupl files push --force --path data/products.csv

✓ Pushed data/products.csv (local kept)

# now push the rest

❯dcupl files push --json

{ "pushed": 2, "version": "draft", "conflicts": 0 }

❯▋

# see what differs between local and server — read-only

❯dcupl files status --json

{
  "push":     ["models/Product.dcupl.json", "workflows/sync.workflow-v3.json"],
  "pull":     ["models/Order.dcupl.json"],
  "conflicts": ["data/products.csv"]
}

# a conflict stops the push — resolve it by choosing a winner

❯dcupl files push --force --path data/products.csv

✓ Pushed data/products.csv (local kept)

# now push the rest

❯dcupl files push --json

{ "pushed": 2, "version": "draft", "conflicts": 0 }

❯▋

Configure credentials

Run dcupl config set once per workspace. Interactive by default; it writes dcupl.config.json (workspace config) and dcupl.secrets.json (your API key). Pass flags to skip the prompts for scripts and CI.

Credential precedence. The CLI resolves each value in this order: command flag → environment variable (DCUPL_API_KEY, DCUPL_PROJECT_ID, DCUPL_CONSOLE_API_URL) → the stored dcupl.secrets.json / dcupl.config.json. CI should inject the key via the env var or --api-key, never a committed file.

Add dcupl.secrets.json and .dcupl/ to your .gitignore before your first commit — the secrets file holds your API key and .dcupl/ holds local sync state.

config set flags

Flag	Purpose
`--project-id <str>`	Console project identifier
`--api-key <str>`	API key for the project
`--console-api-url <str>`	Console API base URL (self-hosted only)
`--yes`	Non-interactive; accept defaults and skip prompts

Config files

File	Contents	Commit?
`dcupl.config.json`	Workspace config (project id, version, settings)	Yes
`dcupl.secrets.json`	API key	No — gitignore
`dcupl/dcupl.lc.json`	Loader config (models, sources)	Yes
`.dcupl/sync-state/`	Local sync ledger	No — gitignore

Resolving conflicts

When both sides changed the same file, sync reports the conflict and stops — there is no auto-merge. Choose a winner with --force: push --force keeps local and overwrites the server; pull --force takes the server and overwrites local.

Version resolution

Most commands accept --version (or -v). The CLI resolves the target version in this order:

1The explicit --version flag, if passed
2The current HEAD recorded in your sync-state
3A fallback of draft

Pushing to production is rejected. Promote to production through Console, not the CLI.

Sync commands

Command	What it does
`dcupl files status [--version <id>]`	Show local vs. server differences. Read-only.
`dcupl files push [--strict] [--yes] [--force]`	Upload new and changed files
`dcupl files pull [--strict] [--yes] [--force]`	Download new and changed files
`dcupl files list [--search <str>] [--tree]`	List server files, filtered or as a tree

Single-file operations

For surgical changes, work on one file at a time instead of a full sync.

Command	What it does
`dcupl files read --path <str>`	Print a remote file's contents
`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>`	Rename/move a file (remote-only)
`dcupl files copy --from <str> --to <str>`	Copy a file (remote-only)
`dcupl files create-folder --path <str>`	Create a remote folder

Managing versions

Versions group a complete set of files — list, snapshot, and remove them.

Command	What it does
`dcupl files versions list`	List all versions
`dcupl files versions copy --from <id> --to <id>`	Snapshot all files from one version into another
`dcupl files versions delete <id> [--yes]`	Delete a version