@devspeak/cli

@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

• Generate an API key from the DevSpeak dashboard (Settings → API Keys)
• 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