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

# Quickstart

> Install the Cargo CLI, authenticate, scaffold a workspace, define a tool, and deploy it — end to end.

This walks you from zero to a deployed, runnable tool. It takes a few minutes and one login shared by the CLI, the CDK, and Cargo Skills.

## 1. Install

```bash theme={null}
npm install -g @cargo-ai/cli
```

Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

## 2. Authenticate

Log in with your API token (create one under **Settings > API** in your Cargo workspace):

```bash theme={null}
cargo-ai login --token <your-api-token>
```

To target a specific workspace, set the `CARGO_WORKSPACE_UUID` environment variable — otherwise commands run against the token's default workspace.

<Warning>
  API token values are shown only once at creation time. Store them immediately
  in a secrets manager (GitHub Secrets, AWS Secrets Manager, 1Password, …).
</Warning>

Verify:

```bash theme={null}
cargo-ai whoami
# → {"user":{"email":"you@example.com"},"workspace":{"name":"My Workspace"}}
```

<Tip>
  In CI or an AI coding agent, you can skip `cargo-ai login` entirely and set the
  token via the `CARGO_API_TOKEN` environment variable — it takes precedence over
  saved credentials: `export CARGO_API_TOKEN=<your-api-token>`.
</Tip>

## 3. Scaffold a workspace

```bash theme={null}
cargo-ai cdk init my-workspace
cd my-workspace
npm install
```

`cdk init` writes a starter project (pass `--template full` for the complete, wired example described in [Project layout](/get-started/project-layout)). The `blank` default gives you a single `cargo.ts` with one AI-powered tool — it needs **no third-party API keys**, so you can deploy and run it with nothing but your Cargo login:

```ts cargo.ts theme={null}
import { defineTool, defineWorkflow } from "@cargo-ai/cdk";
import { z } from "zod";

const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string() }),
  },
  ({ input, ai }) => {
    const company = ai(
      `What company owns the email domain of ${input.email}? Reply with just the company name.`,
    );
    return { company };
  },
);

export const enrich = defineTool("enrich", {
  workflow: enrichFlow,
  description: "Enrich a contact with firmographic data.",
  emojiSlug: "mag",
});
```

## 4. Generate types (optional but recommended)

```bash theme={null}
cargo-ai cdk types
```

This reads your workspace and writes typed connector/model config and the `integrations.*` action registry into `.cargo-ai/`, so your editor autocompletes real action slugs.

## 5. Plan and deploy

```bash theme={null}
cargo-ai cdk plan               # offline diff — no API calls
cargo-ai cdk deploy             # create everything; writes cargo.state.json
```

`deploy` applies in dependency order and records each resource's real uuid in `cargo.state.json`. **Commit that file** — the next deploy only changes what changed.

## 6. Run your tool

```bash theme={null}
cargo-ai orchestration tool list                         # → workflowUuid
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"email":"ada@acme.com"}' \
  --wait-until-finished
```

The run's output includes the company name — your first deployed tool, end to end. It's also live in your workspace at [app.getcargo.io](https://app.getcargo.io), where you can open it in the visual editor and inspect its runs.

## 7. Wire a real data source (optional)

Connectors bring your CRM, warehouse, and enrichment providers into the same file — for example HubSpot, using a [private-app token](/integration/hubspot) kept out of git with `secret()`:

```ts cargo.ts theme={null}
export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});

export const contacts = defineModel("contacts", {
  dataset: hubspot,
  extractSlug: "fetchRecords",
});
```

```bash theme={null}
export HUBSPOT_API_KEY=...      # secret() reads this at deploy time
cargo-ai cdk deploy             # only the new resources are created
```

<Tip>
  `secret()` reads from `process.env` at deploy time. See [Secrets &
  environments](/reference/secrets-and-environments) for `secret()` vs `env()`,
  the `CARGO_*` variables, and deploying the same code to a second workspace.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Project layout" icon="folder-tree" href="/get-started/project-layout">
    How the loader turns a folder of files into a workspace.
  </Card>

  <Card title="CLI, CDK & Skills" icon="signs-post" href="/get-started/cli-cdk-and-skills">
    The three ways to drive Cargo — and when to reach for each.
  </Card>

  <Card title="Connectors" icon="plug" href="/connectors/overview">
    Link your CRM, warehouse, enrichment, and AI providers.
  </Card>

  <Card title="Deploying" icon="rocket" href="/deploy/deploying">
    plan, deploy, prune, refresh, import, and destroy.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/overview">
    Run tools, trigger plays, and query your data from the terminal.
  </Card>
</CardGroup>