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

# Authentication

> How to sign in with the CLI, pass a bearer token to the REST API, and discover OAuth metadata.

There is **one credential**. The CLI holds it, and everything reads it: the REST API, the CDK, the skills, and the MCP bridge. Sign in once and nothing else needs configuring.

```sh theme={null}
npm install -g @cargo-ai/cli
cargo-ai login --email you@company.com
```

A new account starts with 100 free credits and needs no card. `--email` mails a one-time code and creates the account and a workspace on first use.

## Methods

| You are                            | Use                                                   | Browser |
| ---------------------------------- | ----------------------------------------------------- | ------- |
| An agent, a sandbox, CI, any shell | `cargo-ai login --email you@company.com`              | no      |
| A person at a workstation          | `cargo-ai login --oauth`                              | yes     |
| CI with a token already issued     | `cargo-ai login --token <token>` or `CARGO_API_TOKEN` | no      |

In an agent or sandbox shell with no terminal to prompt at, the first `--email` call sends the code and exits. Re-run it with `--code`.

## Calling the API

```bash theme={null}
curl https://api.getcargo.io/v1/storage/models/list \
  -H "Authorization: Bearer $CARGO_API_TOKEN"
```

See [API Reference](/api-reference/introduction) for the rest of the surface.

## OAuth

Authorization-server metadata (RFC 8414): [https://auth.getcargo.io/.well-known/oauth-authorization-server](https://auth.getcargo.io/.well-known/oauth-authorization-server). Device code, authorization code with PKCE (S256), registration, and revocation.

The product MCP server at `https://mcp.getcargo.io` challenges with OAuth. See [MCP servers](/mcp-servers/overview).

## Machine-readable walkthrough

The WorkOS `auth.md` walkthrough — Discover, Pick a method, Register, Claim, Use, Revocation — is [https://www.getcargo.ai/auth.md](https://www.getcargo.ai/auth.md).