.md

Quickstart

The CLI is the agent's way into dcupl, and yours: it reads the real model, answers in structured JSON with --json, and stages data changes until one dcupl app build applies them, when you say so. In a few minutes you'll scaffold a complete dcupl project, run it locally, connect it to the dcupl cloud, and push your files. Each step builds on the last — by the end you'll have a working project synced to the Console.

New to dcupl? Start with How the CLI works for the concepts and a glossary. Building with an agent? The dcupl skill for Claude Code adds command patterns and known pitfalls; see Build with agents.

Install the CLI with npm i -g @dcupl/cli (or run it via npx) — see Installation for prerequisites and troubleshooting.

Jump to a taskScaffoldQuery data locallySync with the cloudRun workflowsCommandsHow it works

The whole flow

zsh — zero to synced

scaffold a project from the minimal starter: dcupl init my-project --starter minimal && cd my-project — output: ## dcupl project created ## Next steps: …

run it locally: dcupl serve — output: ## dcupl development server running at http://localhost:8083 🚀 ##

wire up cloud credentials: dcupl config set --project-id PRJ_42 --api-key <api-key> --yes — output: Wrote dcupl.config.json (…) Wrote dcupl.secrets.json (…)

push your files to versioned cloud storage: dcupl files push — output: Pushed to version: draft Uploaded (3) ✓ dcupl.lc.json ✓ models/a.dcupl.json ✓ data/a.data.json

  1. Scaffold a project

    Create a new project from the default minimal starter. It generates a ready-to-run project complete with a sample model and data. 

    dcupl init my-project --starter minimal
cd my-project

    A couple of handy options:

    dcupl init --here --starter minimal

  2. Explore the project structure

    The minimal starter lays out a typical dcupl workspace:

    my-project
    my-project/
├── dcupl.config.json         # Workspace config (paths, project ID)
├── dcupl.secrets.json        # Your API key (gitignored)
├── .env.example              # Template for .env (DCUPL_API_KEY / DCUPL_PROJECT_ID)
├── .gitignore
├── .vscode/settings.json     # JSON schemas for dcupl files in VS Code
├── package.json
├── readme.md
└── dcupl/
    ├── dcupl.lc.json         # Loader config (resources, applications, environments)
    ├── models/
    │   └── a.dcupl.json      # A sample model definition
    └── data/
        └── a.data.json       # Sample data
    Note

    dcupl.config.json sits at the project root and points at the dcupl/ folder via loaderPath, modelsBasePath, and dataBasePath. Model files use the .dcupl.json extension and data files use .data.json.

  3. Run the dev server

    Start the local development server. It listens on port 8083 by default and opens the welcome screen in your browser; pass --no-open-browser (or set "openBrowser": false in dcupl.config.json) to keep it closed. 

    dcupl serve
dcupl serve --no-open-browser

  4. Connect to the cloud

    You'll need a project ID and API key from the dcupl Console — create a project there to get them; Your first console project walks through it. Then configure your credentials interactively: the non-secret projectId is written to dcupl.config.json and the apiKey to dcupl.secrets.json. For scripts and CI, set them non-interactively. 

    # interactive — prompts for project ID + API key
dcupl config set

# non-interactive, for scripts and CI
dcupl config set --project-id <id> --api-key <key> --yes
    Watch out

    dcupl.secrets.json contains your API key. The .gitignore that dcupl init scaffolds already lists it. With --here in a folder that already has a .gitignore, add dcupl.secrets.json and .env yourself, and never commit the key.

    An agent can run every step from here on for you: Agent setup installs the dcupl skill so the agent knows these commands and their pitfalls.

  5. Push to the cloud

    Upload your workspace files to versioned cloud storage. files push is incremental — it uploads only the files that changed since your last sync. Once it completes, your project is available in the Console. 

    dcupl files push

Project files

Your workspace contains a few key files. Know which ones are safe to commit.

File Purpose Commit?
dcupl.config.jsonWorkspace config: paths + projectId (no secrets)Yes
dcupl.secrets.jsonYour apiKey — secretNo — gitignore
dcupl/ (folder)Your source: loader config, models, and dataYes
dcupl/dcupl.lc.jsonLoader config (resources such as models and data, applications, environments)Yes
.env (optional)DCUPL_API_KEY / DCUPL_PROJECT_ID; overrides the JSON filesNo — gitignore
.dcupl/ (hidden)CLI-managed local sync ledger — not sourceNo — the CLI writes .dcupl/.gitignore itself