One binary, one login
Everything runs through a single binary,cargo-ai, installed and authenticated once (see the Quickstart) — every mode below reuses that same session:
- Imperative commands —
cargo-ai orchestration run create,cargo-ai storage model list, … operate the platform directly. - The CDK ships inside the same binary as
cargo-ai cdk(plan,deploy,refresh,destroy). There is no separate install or login. - Skills are prompt packages that teach an AI agent to call those same commands for you.
The three modes
| Mode | You write… | Reach for it when… |
|---|---|---|
| CLI (imperative) | one-off commands in a terminal or script | you want to run, inspect, or script a single operation — enrich a record, trigger a batch, query data, chat with an agent — without managing state |
| CDK (declarative) | define* TypeScript files, deployed with cargo-ai cdk deploy | you want your whole workspace as versioned, diffable code with plan/deploy and drift detection |
| Skills (agent-driven) | plain-English prompts to an AI agent | you want an agent to figure out the exact commands and UUIDs from a description of the goal |
How they fit together
- Declarative is the default for anything you keep. Connectors, models, tools, agents, and plays belong in a CDK workspace so they’re reproducible. Start with the Quickstart.
- Imperative is for operating what you’ve deployed. Once a tool or play exists, you run and monitor it with CLI commands — one-offs, CI jobs, data pulls.
- Skills sit on top of the CLI. They’re the imperative surface, driven by an agent instead of your fingers. See Skills.
A quick rule of thumb: if you’d commit it to git, define it with the CDK.
If you’d type it once, use the CLI. If you’d rather describe it than
remember the flags, use Skills.
Next steps
Quickstart
Deploy your first workspace with the CDK.
Project layout
How a folder of define* files becomes a workspace.
CLI
The imperative command surface — runs, batches, queries, and more.
Skills
Drive the CLI with natural language through an AI agent.