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 \
  --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?

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:

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> --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:

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 --json)
ID=$(echo "$CONTENT" | jq -r .content_id)

dl score "$ID" --json
dl content get "$ID" --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.

Welcome

Getting Started

Core Concepts

Prompting Guide

Tools

Resources

CLI Quickstart

CLI Quickstart

Install

1. Log in

2. Add a reference material

3. Generate

4. Finalize and follow up

Workspaces

Scopes in practice

Headless / agent loops

Next steps

API Key Scopes

Authentication

API Overview

Templates as Vessels

​CLI Quickstart

​Install

​1. Log in

​2. Add a reference material

​3. Generate

​4. Finalize and follow up

​Workspaces

​Scopes in practice

​Headless / agent loops

​Next steps

API Key Scopes

Authentication

API Overview

Templates as Vessels

CLI Quickstart

Install

1. Log in

2. Add a reference material

3. Generate

4. Finalize and follow up

Workspaces

Scopes in practice

Headless / agent loops

Next steps