> ## 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 https://api.getcargo.io/INSTALL.md` 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://raw.githubusercontent.com/getcargohq/cargo-skills/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.

# Commands, project & skills

> Three ways to operate Cargo through one binary and one login: imperative commands for one-off work, a declarative project 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 project** ships *inside* the same binary as `cargo-ai project` (`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 project" is not a real choice of tools — `project` is a command group of the CLI. The real choice is *which mode fits the task*.

<Note>
  `cargo-ai project` used to be called `cargo-ai cdk`, and `cdk` still works as
  an alias — nothing you have written down needs changing. The TypeScript
  library you import from is still [`@cargo-ai/cdk`](https://www.npmjs.com/package/@cargo-ai/cdk).
</Note>

## 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 project plan / deploy (define* files + state)"]
  bin --> agent["<b>Agent-driven</b><br/>Skills → natural language → CLI commands"]
```

| Mode                      | You write…                                                          | Reach for it when…                                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Commands** (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 |
| **Project** (declarative) | `define*` TypeScript files, deployed with `cargo-ai project 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 [project](/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 in the
  **project**. If you'd type it once, use a **command**. 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 from a project.
  </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>