# Recipes

Each recipe pairs a plain-language prompt with the exact CLI commands the agent runs — and what you get back. Watch how the [dcupl skill](/agentic/the-skill) turns a request into a sequence of inspectable steps, then reuse them as templates for your own prompts.

**Before you start.** Recipes 03–05 run inside a dcupl workspace: scaffold one with `dcupl init my-shop --starter empty` or work in an existing one. Recipes 04 and 05 call your Console project, so set credentials first with `dcupl config set --project-id <project-id> --api-key <api-key> --yes`. The outputs are trimmed examples: ids, ports, counts and runner uids differ on your machine.

## Profile a CSV

> **You:** What's in products.csv, and what's the price distribution?

The agent runs

```console
# spin up an in-memory daemon that applies changes immediately
$ dcupl app create --auto-update --json
{ "appId": "swift-otter-3a1f", "port": 52341 }

# ingest the CSV, sampling 100 rows to infer types
$ dcupl app data upsert --file products.csv --model Product \
  --key-property id --auto-generate-sample-size 100 --json
{ "upserted": 1284, "model": "Product", "built": true }

# read back the category breakdown
$ dcupl app fn facets --model Product --attribute category --json
[
  { "value": "Outerwear", "count": 412 },
  { "value": "Footwear",  "count": 358 },
  { "value": "Accessories","count": 514 }
]

# and the price distribution
$ dcupl app fn aggregate --model Product --attribute price \
  --types avg,min,max --json
{ "attribute": "price", "types": ["avg", "min", "max"], "avg": 84.27, "min": 4.99, "max": 489 }
```

The agent spins up a daemon (a live in-memory dcupl SDK instance that holds your data), ingests the CSV, then reads back category facets and price stats — and keeps the daemon alive for your follow-up questions.

## Stage changes, then build

> **You:** Apply this price update, but let me see what changes before it takes effect.

The agent runs

```console
# create a daemon WITHOUT --auto-update, so mutations stage instead of applying
$ dcupl app create --json
{ "appId": "swift-otter-3a1f", "port": 52341 }

# ingest the new prices (inferring the model) — staged, not yet live (built: false)
$ dcupl app data upsert --file new-prices.csv --model Product \
  --key-property id --auto-generate-sample-size 100 --json
{ "upserted": 37, "model": "Product", "built": false,
  "hint": "changes staged; run 'dcupl app build' to apply (or create the daemon with --auto-update)" }

# correct one price — also staged on top of the first (update only changes existing keys)
$ dcupl app data update --model Product --key-property id \
  --content '[{"id":"SKU-9","price":79.9}]' --json
{ "updated": 1, "skipped": 0, "skippedKeys": [], "model": "Product", "built": false,
  "hint": "changes staged; run 'dcupl app build' to apply (or create the daemon with --auto-update)" }

# apply every staged change in one build — now queries see the new state
$ dcupl app build --json
{ "appId": "swift-otter-3a1f", "built": true }
```

Without --auto-update, each mutation stages and reports built: false (dcupl app status reports pendingChanges: true), and queries keep answering from the last build until dcupl app build applies every staged change in one update. This is the explicit stage → build lifecycle that keeps agent-driven changes reviewable.

## Model your data & validate

> **You:** Turn this CSV into a proper model.

The agent runs

```console
# infer a model from the data (kept in dcupl/data/) and register model + data in dcupl.lc.json
$ dcupl generate model --from dcupl/data/products.csv --name Product --register
Model resource added to dcupl/dcupl.lc.json
Data resource added to dcupl/dcupl.lc.json
Model written to ~/my-shop/dcupl/models/Product.dcupl.json
Inferred 9 properties.
  All columns inferred cleanly.
Key strategy: keyProperty = "id" (only unique key-like column).

# confirm the project loads cleanly: load.ok and zero critical findings (ok only means a report was produced)
$ dcupl validate --json
{
  "ok": true,
  "source": { "mode": "local", "loaderPath": "dcupl/dcupl.lc.json" },
  "load": { "ok": true },
  "models": { "total": 1, "empty": [], "autoGenerated": [] },
  "errors": { "total": 0, "bySeverity": { "critical": 0, "warning": 0 }, "byGroup": {}, "byType": {},
              "truncatedGroups": [], "records": [] },
  "summary": { "critical": 0, "warnings": 0 }
}
```

The agent infers a model from the data, registers it in your project, then validates the configuration so you start from a clean baseline. The registered data resource points at ${baseUrl}/data/<file name>, so the source file has to live in dcupl/data/ — otherwise validate reports an InvalidResource and an empty model.

## Build, test & deploy a workflow

> **You:** Create a workflow that fetches X and writes it.

The agent runs

```console
# start from the curated schema example (the plain-text output also holds the schema source, so take .example from --json), or run dcupl generate workflow --name sync for a read → transform → write preset at the same path (set its dcuplFilesApiKey variable before you test it)
$ dcupl schemas get TemplateV3 --example --json \
  | jq -r .example > dcupl/workflows/sync.workflow-v3.json

# the agent edits sync.workflow-v3.json (key, fetch + write nodes), then validates it locally
$ dcupl workflow validate --file dcupl/workflows/sync.workflow-v3.json
✓ valid (0 warning(s))

# find the runners this project can deploy to
$ dcupl workflow runners list --json
[
  { "uid": "run_dev_2c", "runnerKey": "dev",  "type": "workflow-runner", "url": "https://…", "health": "ok" },
  { "uid": "run_prd_9a", "runnerKey": "prod", "type": "workflow-runner", "url": "https://…", "health": "ok" }
]

# deploy to the dev runner and run the graph once (prints the node-by-node trace)
$ dcupl workflow test --file dcupl/workflows/sync.workflow-v3.json --runner run_dev_2c
Execution 6f1c… — workflow <projectId>-sync
  • trigger [ok, 1ms] → 1 item(s)
  • fetch [ok, 412ms] → 120 item(s)
  • map [ok, 38ms] → 120 item(s)
  • write [ok, 161ms] → 1 item(s)

# deploy to prod once the test passes — waits until the runner has hot-swapped to it
$ dcupl workflow deploy --file dcupl/workflows/sync.workflow-v3.json \
  --runner run_prd_9a --yes
✓ deployed <projectId>-sync (uid 9QeV…, v 3f9c…) — live ✓
```

The agent starts from a real schema example, validates and tests against a dev runner, then deploys to production only after the test passes. deploy and test send the local file but do not sync it to the console — that is what dcupl files push is for (next recipe).

## Sync your project to the cloud

> **You:** Push my changes.

The agent runs

```console
# wire up credentials for the linked project
$ dcupl config set --project-id PRJ_42 --api-key <api-key> --yes
Wrote dcupl.config.json (~/my-shop/dcupl.config.json)
Wrote dcupl.secrets.json (~/my-shop/dcupl.secrets.json)

projectId:      PRJ_42
apiKey:         ***9f2c
consoleApiUrl:  (default)

# 3-way diff: local vs server vs baseline (paths are relative to dcupl/)
$ dcupl files status --json
{
  "success": true, "versionId": "draft", "hasBaseline": true,
  "uploads":   ["models/Product.dcupl.json", "workflows/sync.workflow-v3.json"],
  "downloads": [],
  "conflicts": [],
  "wouldDeleteOnServerInStrictMode": [], "wouldDeleteLocallyInStrictMode": [],
  "unchanged": 14, "needsRepair": []
}

# push — aborts on any conflict instead of overwriting server changes
$ dcupl files push --json
{
  "success": true, "versionId": "draft",
  "uploaded": ["models/Product.dcupl.json", "workflows/sync.workflow-v3.json"],
  "deleted": [], "failed": [], "conflicts": [], "resolvedConflicts": [],
  "unchanged": 14, "unverified": []
}
```

The agent wires up credentials, runs a 3-way status to surface any conflicts, then pushes. A push with conflicts aborts (exit 1, code PUSH\_CONFLICTS, the conflicts listed in the JSON error) unless you pass --force, so nothing overwrites server changes silently.

## Next steps

- [The dcupl skill](/agentic/the-skill) — Why these sequences are the correct ones
- [Schemas](/cli/schemas) — Discover exact schema field names
- [Local data apps](/cli/local-data-apps) — The dcupl app daemon in depth
- [Cloud Sync](/cli/cloud-sync) — Credentials, status, and push/pull