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

# CLI Quickstart

> Authenticate with the DraftLift CLI and run your first generation in under five minutes.

# CLI Quickstart

The `dl` CLI is the fastest way to drive DraftLift from a terminal, a script, or an AI agent. This page takes you from a fresh install to your first generated draft.

## Install

```bash theme={null}
npm install -g @draftlift/cli
dl --version
```

The CLI requires Node.js 22 or later. Verify with `node --version`.

## 1. Log in

```bash theme={null}
dl login
```

`dl login` opens your browser, authenticates against DraftLift, and writes an API key to `~/.draftlift/credentials.json`. If you cannot open a browser (CI, remote shell):

```bash theme={null}
dl login --no-browser            # prints a URL to paste
dl login --api-key dl_live_...   # use an existing key directly
```

You can also set `DRAFTLIFT_API_KEY` in your environment — the CLI prefers it over the saved credentials file, which makes scripted use trivial:

```bash theme={null}
export DRAFTLIFT_API_KEY=dl_live_your_key_here
dl whoami
```

`dl whoami` confirms who you are and surfaces the calling key's metadata:

```bash theme={null}
$ dl whoami --json
{
  "user_id": "u_...",
  "email": "you@example.com",
  "tier": "business",
  "workspace_id": "ws_...",
  "key": {
    "name": "agent-laptop",
    "scopes": ["read", "write"],
    "workspace_id": null
  },
  "trace_id": "tr_..."
}
```

The `key` object is what we'll iterate on next.

## 2. Add a reference material

References give DraftLift source material to draw on. Add one from a URL:

```bash theme={null}
dl references add \
  --url "https://www.paulgraham.com/avg.html" \
  --title "Beating the Averages"
```

Or pipe text from disk via `--stdin`:

```bash theme={null}
cat my-notes.md | dl references add --stdin --title "Internal notes"
```

List what you have:

```bash theme={null}
dl references list --json
```

## 3. Generate

```bash theme={null}
dl generate "Why most B2B blogs are forgettable" \
  --platform linkedin \
  --json
```

The first generation prints a `content_id`, the generated body, token usage, and an estimated cost. Pass `--dry-run` to preview the resolved platform and template, the requested workspace value, and the execution mode without spending tokens. If you omit `--workspace`, the preview shows `null`; the server chooses any API-key-bound or default workspace when you run the generation.

Need to discover what's available?

```bash theme={null}
dl platforms list
dl templates list --platform linkedin
dl memories list
```

Each command supports `--json` and `--help` with concrete examples.

## 4. Finalize and follow up

After editing in the DraftLift editor, inspect the saved result:

```bash theme={null}
dl content get <content_id> --json
```

You can also score, schedule, or repurpose without leaving the terminal:

```bash theme={null}
dl score <content_id>
dl schedule <content_id> --at "2026-06-01T09:00:00Z"
dl repurpose <content_id> --platform x
dl repurpose <content_id> --platform linkedin
```

## Workspaces

If your account has more than one workspace, every workspace-scoped command accepts a `--workspace` flag:

```bash theme={null}
dl references list --workspace ws_abc123
dl generate "..." --platform x --workspace ws_abc123
```

Pass it as a global option to apply to any subcommand:

```bash theme={null}
dl --workspace ws_abc123 references add --url "..." --title "..."
```

If your API key is bound to a single workspace at creation time, you can omit `--workspace` — the server resolves it for you. Passing a different `--workspace` value against a bound key returns `403 workspace_mismatch`. See [API Key Scopes & Workspace Binding](/quickstart/api-key-scopes) for the full model.

## Scopes in practice

API keys carry one or more scopes. The CLI maps scope errors to a typed exit code (2) with the upgrade URL on its own line:

```bash theme={null}
$ dl references add --url "..." --title "..."
Error: This endpoint requires the 'write' scope.
  Required scope: write
  Current scopes: read
  Upgrade: https://app.draftliftai.com/settings/api-keys
```

To fix: re-issue the key from **Settings → API Keys** with the **Write** checkbox enabled. See [API Key Scopes & Workspace Binding](/quickstart/api-key-scopes) for guidance on choosing scopes.

## Headless / agent loops

The CLI is designed to be driven by other programs. Every command supports `--json`, returns a `trace_id` you can log, and uses non-zero exit codes for typed errors (1=user, 2=auth, 3=server, 4=not found). A minimal agent loop:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

CONTENT=$(dl generate "$1" --platform linkedin --json)
ID=$(echo "$CONTENT" | jq -r .content_id)

dl score "$ID" --json
dl content get "$ID" --json
```

## Next steps

<CardGroup cols={2}>
  <Card title="API Key Scopes" icon="key" href="/quickstart/api-key-scopes">
    Choose the right scopes and decide when to bind a key to a workspace.
  </Card>

  <Card title="Authentication" icon="lock" href="/api-reference/authentication">
    Full reference for keys, scopes, workspace binding, and error shapes.
  </Card>

  <Card title="API Overview" icon="code" href="/api-reference/introduction">
    Use the same endpoints from any HTTP client.
  </Card>

  <Card title="Templates as Vessels" icon="flask" href="/guides/templates-as-vessels">
    Understand how templates shape output across platforms.
  </Card>
</CardGroup>