> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# CLI, CDK & Skills

> Three ways to operate Cargo through one binary and one login: imperative CLI commands for one-off work, declarative CDK for a whole workspace in git, and agent Skills so Claude Code, Codex, or Cursor can do it from a plain-English request. Signing up is free — 100 credits, no card.

There are three ways to drive Cargo, and they're not separate tools — they're three modes of the **same** command-line tool.

## One binary, one login

Everything runs through a single binary, `cargo-ai`, installed and authenticated once (see the [Quickstart](/get-started/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.

So "CLI vs CDK" is not a real choice of tools — the CDK is a subcommand of the CLI. The real choice is *which mode fits the task*.

## The three modes

```mermaid theme={null}
flowchart TD
  bin["cargo-ai — one binary, one login"]
  bin --> imp["<b>Imperative</b><br/>cargo-ai orchestration / storage / connection / ai …"]
  bin --> dec["<b>Declarative</b><br/>cargo-ai cdk plan / deploy (define* files + state)"]
  bin --> agent["<b>Agent-driven</b><br/>Skills → natural language → CLI commands"]
```

| 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](/get-started/project-layout) so they're reproducible. Start with the [Quickstart](/get-started/quickstart).
* **Imperative is for operating what you've deployed.** Once a tool or play exists, you run and monitor it with [CLI commands](/cli/overview) — 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](/skills/overview).

<Note>
  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**.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/get-started/quickstart">
    Deploy your first workspace with the CDK.
  </Card>

  <Card title="Project layout" icon="folder-tree" href="/get-started/project-layout">
    How a folder of define\* files becomes a workspace.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/overview">
    The imperative command surface — runs, batches, queries, and more.
  </Card>

  <Card title="Skills" icon="robot" href="/skills/overview">
    Drive the CLI with natural language through an AI agent.
  </Card>
</CardGroup>