@devspeak/cli

Command-line interface for the DevSpeak technical translation API.

Installation

# Install globally from npm
npm install -g @devspeak/cli

# Or run directly with npx (no install needed)
npx @devspeak/cli --help

Development (from monorepo)

cd packages/cli
pnpm install
pnpm link --global

Setup

1. Generate an API key from the DevSpeak dashboard (Settings → API Keys)
2. Authenticate the CLI:

devspeak login
# Enter your API key when prompted

# Or pass it directly
devspeak login --key dsk_live_your_api_key_here

This saves your key to $XDG_CONFIG_HOME/devspeak/config.json, defaulting to ~/.config/devspeak/config.json, with permissions restricted to your user (mode 0600). A pre-existing ~/.devspeakrc is migrated automatically — see Config File.

Check your identity (whoami)

devspeak whoami          # masked key, key source, endpoint, config path
devspeak whoami --json   # machine-readable

When no key is configured, whoami prints guidance to run devspeak login and exits 1. The DEVSPEAK_API_KEY environment variable takes precedence over the stored key and is reported as environment in the Source field.

Log out (logout)

devspeak logout

Removes the stored API key while keeping the endpoint and generation defaults. Idempotent — running it with no stored key succeeds. If DEVSPEAK_API_KEY is set, the CLI warns that the environment variable still grants access and must be unset manually (unset DEVSPEAK_API_KEY). Logging out does not revoke the key itself; revoke it in DevSpeak under Settings → API Keys.

Usage

Workflow note: The CLI's translate command triggers Translation Execution (Stage 2 of the DevSpeak workflow) — it generates a formal technical specification from informal input. The refine command triggers Post-Generation Refinement (Stage 3) — it iteratively modifies previously generated output. These are distinct lifecycle stages. See ARCHITECTURE.md for the full three-stage workflow.

Translate text (translate)

The translate command is the primary Translation Execution trigger. It transforms informal text into a formal, audience-specific technical specification.

# Positional argument
devspeak translate "We need a login page that works with Google and saves user data"

# Pipe from stdin
echo "We need a caching layer for our API" | devspeak translate

# From a file
cat requirements.txt | devspeak translate --format "Jira Tickets"

devspeak optimize remains as a deprecated alias for translate.

Options

| Flag | Description | Default | | --------------------------- | --------------------------------------------------------------- | ---------------- | | -a, --audience <value> | Target audience | Senior Dev | | -c, --context <value> | Tech context | Backend | | -f, --format <value> | Output format | Technical Spec | | -t, --tone <number> | Tone 0 (concise) to 100 (detailed) | 75 | | -i, --instructions <text> | Custom instructions | — | | --file <path> | Attach a local file as context (PDF, Markdown, TXT — max 10 MB) | — | | -o, --output <file> | Write output to file | — | | --json | Output raw JSON response | — |

Audience values

Junior Dev, Senior Dev, Tech Lead, SRE, Data Engineer

Context values

Backend, Frontend, Mobile, Data/ML, DevOps

Format values

Technical Spec, Jira Tickets, API Design, RFC, Data Model, Prompt, Optimize

Examples

# Generate Jira tickets for a mobile feature
devspeak translate "Add push notifications for order updates" \
  --audience "Tech Lead" \
  --context "Mobile" \
  --format "Jira Tickets" \
  --tone 80

# Create an API design doc and save to file
devspeak translate "REST API for managing user subscriptions" \
  --format "API Design" \
  --output api-design.md

# Get concise output (tone < 50 triggers rewrite mode)
devspeak translate "we need to make the app faster" --tone 30

# Pipe output as JSON for scripting
devspeak translate "Add rate limiting to all endpoints" --json | jq '.output'

# Attach a PRD as context when generating a technical spec
devspeak translate "Implement the user authentication flow" \
  --file ./docs/product-requirements.pdf \
  --audience "Tech Lead" \
  --format "Technical Spec" \
  --tone 85

# Attach a Markdown runbook as context for an SRE RFC
devspeak translate "Add Redis caching for API responses" \
  --audience "SRE" \
  --context "DevOps" \
  --format "RFC" \
  --tone 90 \
  --instructions "Include monitoring and alerting requirements" \
  --file ./runbooks/caching-standards.md

Refine translation (refine)

The refine command performs Post-Generation Refinement (Stage 3). It takes a previous translation output and user feedback, then produces a complete replacement document incorporating the requested changes.

# Refine output read from a file (@ prefix reads the file)
devspeak refine --previous @spec.md \
  --feedback "Add a section on rate limiting and include error codes"

# Refine inline text
devspeak refine --previous "## Spec\n..." \
  --feedback "Restructure as a numbered list" --json

# Chain translate into refine
devspeak translate "Add push notifications" -o spec.md
devspeak refine -p @spec.md -F "Shorten to three bullet points" -o spec.md

| Flag | Description | Required | | ----------------------- | ----------------------------------------------------- | -------- | | -p, --previous <text> | Previous output to refine (@path reads from a file) | Yes | | -F, --feedback <text> | Feedback describing the change | Yes | | -r, --original <text> | Original input text, for additional context | No |

refine also accepts the same -a/-c/-f/-t/-o/--json flags as translate.

Important: refine operates on generated output (post-translation), not on raw user input. To optimize raw input text before translating, use the web app's Optimize button (Lexical Optimization, Stage 1).

Configuration

# View current config
devspeak config show

# Change default endpoint
devspeak config set endpoint https://www.devspeak.dev

# Change default audience
devspeak config set audience "Tech Lead"

Config File

Stored at $XDG_CONFIG_HOME/devspeak/config.json, defaulting to ~/.config/devspeak/config.json (mode 0600).

A pre-existing ~/.devspeakrc is still read, and is migrated automatically to the new location the first time the config is written. The old file is kept as ~/.devspeakrc.migrated.

{
  "apiKey": "dsk_live_...",
  "endpoint": "https://www.devspeak.dev",
  "defaults": {
    "audience": "Senior Dev",
    "context": "Backend",
    "format": "Technical Spec",
    "tone": 75
  }
}

config set validates values against the same allowed sets the API enforces, so an invalid audience, context, format, tone, or endpoint fails locally.

Updates

devspeak update        # check the npm registry and print the upgrade command
devspeak update --yes  # install the update via npm install -g

The CLI also performs a passive update check: at most once every 24 hours, a detached background process refreshes the latest known version from the npm registry, and the next run prints a one-line notice on stderr when an update is available. The check is TTY-only, skipped in CI, and never blocks or fails a command. Opt out with:

export DEVSPEAK_DISABLE_UPDATE_CHECK=1

Diagnostics

devspeak doctor        # one-shot environment audit
devspeak doctor --json # machine-readable

Checks: Node version (≥ 18), config file parses, API key present and dsk_-prefixed, config permissions (0600), endpoint health (GET /api/v1/health), and installed version vs the npm registry. Each failed check prints an actionable fix line. Exits 0 only when every check passes.

Shell Completions

# bash
devspeak completion bash >> ~/.bashrc

# zsh
devspeak completion zsh > "${fpath[1]}/_devspeak"

# fish
devspeak completion fish > ~/.config/fish/completions/devspeak.fish

Exit Codes

| Code | Meaning | | ---- | ------------------------------------------------------------ | | 0 | Success | | 1 | Validation error, API error, network failure, or write error |

The generated document goes to stdout; every diagnostic, warning, and metadata line goes to stderr, so devspeak translate ... > out.md is safe. Color is disabled automatically when stderr is not a TTY, honors NO_COLOR, and can be forced off with the global --no-color flag.

Privacy

The CLI sends no telemetry. It stores your API key in the config file above (0600) and sends the text you translate to the DevSpeak API, which processes it as described in the Privacy Policy. The once-a-day update check contacts only the npm registry; disable it with DEVSPEAK_DISABLE_UPDATE_CHECK=1.

Environments

| Environment | Endpoint | | ----------- | -------------------------- | | Production | https://www.devspeak.dev |

Switch environments:

devspeak config set endpoint https://www.devspeak.dev