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

# CLI, CDK & Skills

> Three ways to operate Cargo — imperative CLI commands, declarative CDK workspaces, and agent-driven Skills — all through one binary and one login.

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>