@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
npm install
npm link

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 ~/.devspeakrc with permissions restricted to your user (chmod 600).

Usage

Workflow note: The CLI's optimize 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 (optimize)

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

# Positional argument
devspeak optimize "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 optimize

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

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 | — | | -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 optimize "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 optimize "REST API for managing user subscriptions" \
  --format "API Design" \
  --output api-design.md

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

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

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 a previously saved translation
devspeak refine --translation-id translation_abc123 \
  --feedback "Add a section on rate limiting and include error codes"

# Refine with JSON output for scripting
devspeak refine --translation-id translation_abc123 \
  --feedback "Restructure as numbered list" --json

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 ~/.devspeakrc:

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

Environments

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

Switch environments:

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