# 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](/cli/how-it-works) for the concepts and a glossary. Building with an agent? The [dcupl skill](/agentic/the-skill) for Claude Code adds command patterns and known pitfalls; see [Build with agents](/agentic).

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

The whole flow

```console title="zsh — zero to synced"
# scaffold a project from the minimal starter
$ dcupl init my-project --starter minimal && cd my-project
##  dcupl project created  ##
Next steps: …

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

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

# push your files to versioned cloud storage
$ dcupl files push
Pushed to version: draft

Uploaded (3)
  ✓ dcupl.lc.json
  ✓ models/a.dcupl.json
  ✓ data/a.data.json
```

## Step 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.

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

A couple of handy options:

**Into current dir**

```bash
dcupl init --here --starter minimal
```

**Bare project**

```bash
dcupl init my-project --starter empty
```

## Step 2: Explore the project structure

The `minimal` starter lays out a typical dcupl workspace:

```text filename="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`.

## Step 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.

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

## Step 4: Connect to the cloud

You'll need a project ID and API key from the [dcupl Console](https://console.dcupl.com) — create a project there to get them; [Your first console project](/console/getting-started) 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.

```bash
# 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](/agentic/setup) installs the dcupl skill so the agent knows these commands and their pitfalls.

## Step 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.

```bash
dcupl files push
```

## Project files

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

| File | Purpose | Commit? |
| --- | --- | --- |
| `dcupl.config.json` | Workspace config: paths + projectId (no secrets) | Yes |
| `dcupl.secrets.json` | Your apiKey — secret | No — gitignore |
| `dcupl/ (folder)` | Your source: loader config, models, and data | Yes |
| `dcupl/dcupl.lc.json` | Loader config (resources such as models and data, applications, environments) | Yes |
| `.env (optional)` | DCUPL\_API\_KEY / DCUPL\_PROJECT\_ID; overrides the JSON files | No — gitignore |
| `.dcupl/ (hidden)` | CLI-managed local sync ledger — not source | No — the CLI writes .dcupl/.gitignore itself |

## Next steps

- [Scaffolding](/cli/scaffolding) — Starters, generators, and project layout
- [Local data apps](/cli/local-data-apps) — Query your data with the local daemon
- [Cloud Sync](/cli/cloud-sync) — Credentials, push, pull, and versioning
- [How the CLI works](/cli/how-it-works) — The mental model behind workspace, daemon, and cloud
- [Your first console project](/console/getting-started) — Create the project and API key step 4 needs
- [Agent setup](/agentic/setup) — Let an agent drive the CLI with the dcupl skill