Skip to main content

​
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

npm install -g @draftlift/cli
dl --version
The CLI requires Node.js 22 or later. Verify with node --version.

​
1. Log in

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): 
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: 
export DRAFTLIFT_API_KEY=dl_live_your_key_here
dl whoami
dl whoami confirms who you are and surfaces the calling key’s metadata: 
$ 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: 
dl references add \
  --url "https://www.paulgraham.com/avg.html" \
  --title "Beating the Averages"
Or pipe text from disk via --stdin: 
cat my-notes.md | dl references add --stdin --title "Internal notes"
List what you have: 
dl references list --json

​
3. Generate

dl generate "Why most B2B blogs are forgettable" \
  --platform linkedin \
  --template "Thread" \
  --json
The first generation prints a content_id, the generated body, token usage, and an estimated cost. Pass --dry-run to see the assembled prompt without spending tokens. Need to discover what’s available? 
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 editor (or from your agent), close the loop: 
dl content update <content_id> --finalized-content "Your edited draft..."
dl content get <content_id> --json
You can also score, schedule, or repurpose without leaving the terminal: 
dl score <content_id>
dl schedule <content_id> --at "2026-06-01T09:00:00Z"
dl repurpose <content_id> --to x --to email

​
Workspaces

If your account has more than one workspace, every workspace-scoped command accepts a --workspace flag: 
dl references list --workspace ws_abc123
dl generate "..." --platform x --workspace ws_abc123
Pass it as a global option to apply to any subcommand: 
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 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: 
$ 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 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: 
#!/usr/bin/env bash
set -euo pipefail

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

# ... your review/edit step ...

dl content update "$ID" --finalized-content "$EDITED" --json

​
Next steps

API Key Scopes

Choose the right scopes and decide when to bind a key to a workspace.

Authentication

Full reference for keys, scopes, workspace binding, and error shapes.

API Overview

Use the same endpoints from any HTTP client.

Templates as Vessels

Understand how templates shape output across platforms.