Tutorial covering the @devspeak/cli npm package: global installation, API key authentication via devspeak login, translating text from arguments or stdin, attaching local PDF and Markdown context with --file, and wiring the CLI into a CI pipeline using the DEVSPEAK_API_KEY environment variable.

Automate Specifications with the DevSpeak CLI

The DevSpeak CLI exposes the same translation engine as the web app, which makes it usable from a terminal, a shell script, or a CI job. This tutorial covers installation through a working CI step.

What You'll Learn

  • Install and authenticate the CLI
  • Translate text from arguments, stdin, and local files
  • Run the CLI non-interactively in CI

    • Prerequisites

  • Node.js 20 or newer
  • A DevSpeak API key from Settings → Keys (requires the Developer tier)

    • Time Estimate

    ~8 minutes

    Step 1 — Install

    ``bash

    npm install -g @devspeak/cli

    `

    Verify the install:

    `bash

    devspeak --version

    `

    Step 2 — Authenticate

    `bash

    devspeak login

    `

    The key is written to $XDG_CONFIG_HOME/devspeak/config.json with mode 600. Confirm it registered:

    `bash

    devspeak whoami

    `

    The output masks the key. It never prints in full, which makes whoami safe to run in a shared terminal.

    Checkpoint

    At this point you should have:

  • [ ] devspeak --version printing a version number

  • [ ] devspeak whoami reporting a masked key and an endpoint

    • If whoami fails, run devspeak doctor for a full environment audit.

    Step 3 — Translate

    Three input paths are available. All three hit POST /api/v1/translate.

    `bash

    Positional argument

    devspeak translate "Users should be able to export their data as CSV"

    Piped from stdin

    cat notes.txt | devspeak translate --format "Jira Tickets"

    With local file context

    devspeak translate "Implement the auth flow" --file ./docs/prd.pdf

    `

    --file accepts PDF, Markdown, and plain text up to 10 MB. Validation happens locally before any network call, so an oversized file fails immediately rather than after an upload.

    Step 4 — Run It in CI

    devspeak login is interactive and will hang in a CI runner. Use the environment variable instead — it takes precedence over any stored key.

    `yaml

  • name: Generate specification

    • env:

    DEVSPEAK_API_KEY: ${{ secrets.DEVSPEAK_API_KEY }}

    run: |

    devspeak translate "$(cat request.txt)" \

    --audience "Senior Dev" \

    --format "Technical Spec" > spec.md

    `

    Because documents go to stdout and diagnostics go to stderr, the redirect above captures only the specification.

    Troubleshooting

    command not found: devspeak

    The global npm bin directory is not on your PATH. Run npm bin -g and add that directory, or invoke it with npx @devspeak/cli.

    401 Unauthorized in CI but not locally

    The runner is reading a different key. DEVSPEAK_API_KEY overrides the config file, so check the secret is exposed to the step and not just the workflow.

    Invalid value for --audience

    Audience, context, format, and tone are validated locally against the same enums the API enforces. Run devspeak translate --help for the accepted values.

    Summary

    You've learned how to:

  • Install and authenticate the CLI

  • Translate from arguments, stdin, and local files
  • Invoke the CLI non-interactively from CI

    • Next Steps

  • Read the [API reference](/docs/api-reference) for direct HTTP access
  • Add devspeak doctor --json` as a pipeline preflight check