# Why it works

Good agentic tooling isn't an accident. The dcupl CLI is agent-friendly because of deliberate design choices that remove ambiguity, make state inspectable, and give the agent a way to discover the truth instead of guessing. Here's what matters and why.

> **How this maps to the [three pillars](/agentic).** Two of the pillars are CLI design choices you'll see below — `--json` everywhere and the stage → build lifecycle. The daemon and schema discovery are two more CLI choices that keep the agent fast and accurate. The third pillar — the [dcupl skill](/agentic/the-skill) — is the other half: it's what teaches the agent to use all of them.

## `--json` everywhere

Every command accepts `--json`. An agent that parses structured output knows precisely what happened — which records changed, what a query returned, whether a deploy succeeded — without scraping human-formatted text. Reliable parsing means reliable next steps. Errors come back on stdout as `{ "success": false, "error": "…", "code": "MODEL_NOT_FOUND" }` with exit code 1, so the agent can branch on `code`. The exceptions are `dcupl config set`, which accepts the flag but prints text, and the long-running `dcupl serve`.

## An explicit stage → build lifecycle

Data mutations stage changes; `dcupl app build` applies them (or `--auto-update` applies them immediately). Because the lifecycle is explicit, the agent can see that changes are pending (every staged mutation reports `"built": false`, and `dcupl app status --json` reports `"pendingChanges": true`), reason about what's about to change, and recover cleanly when something looks wrong. Nothing happens by surprise.

## Stateful daemon reuse

A **daemon** here is a background process the CLI starts with `dcupl app create` — a live, in-memory instance of the dcupl SDK that holds your data and answers queries. It stays alive across calls (until `dcupl app destroy`, or after 30 idle minutes by default — `--idle-timeout`), so the agent creates it once, then runs facets, aggregations, and queries against the same in-memory data — fast follow-ups instead of re-ingesting on every question. Conversations about your data stay responsive. (Full lifecycle: [Local data apps](/cli/local-data-apps).)

## Schema discovery, not guessing

When the agent needs to author against a model or workflow shape, it doesn't invent field names. It runs `dcupl schemas get <Name> --example` to see the real structure first. This single escape hatch eliminates a whole class of silent failures — the wrong field name returning empty results.

## Next steps

- [Agentic Development](/agentic) — The overview and the three pillars
- [Recipes](/agentic/recipes) — These principles applied to real tasks