Specky CLI

What this is for

The Specky CLI gives a technical PM, founder, or product-minded engineer a small, scriptable way to work with the same Product Graph used by the web app, REST API, and MCP server. It is useful when the product question starts in a terminal, a repository, or a scheduled pipeline.

The CLI is a real API client. It does not create a local fake workspace or print pretend results. Every command authenticates to one workspace and uses the same validation, scope, plan limits, and audit trail as the other Specky interfaces.

Before you start

• A Specky workspace and a workspace API key from Settings → Developer.
• Node.js 20 or newer.
• This repository, until the dependency-free package is published to your registry.

Install and authenticate

From the repository root, run:

node ./cli/specky.mjs login --api-key "$SPECKY_API_KEY"

The key is verified against Specky before it is written to ~/.config/specky/config.json. The file is created with owner-only permissions. For CI, keep the key in SPECKY_API_KEY and do not write a local config file.

Commands and expected results

Search

node ./cli/specky.mjs search "invite flow drop-off" --limit 10

This returns a human-readable table of matching graph nodes and documents. Add --json when another command needs the structured results array.

Capture a signal

node ./cli/specky.mjs capture       --content "Customers cannot find the export action"       --type FEEDBACK       --url "https://example.com/customer-review"

The result is a real graph node with the content, source type, URL, and capture method. It becomes searchable and available to AI tools in the same workspace.

Create a document

node ./cli/specky.mjs document create       --title "Invite flow improvement brief"       --type prd       --content "# Problem\n\nTeams cannot invite their colleagues quickly."

The result is a draft document. Its Markdown is indexed so later searches and AI requests can find it.

Run a workflow

node ./cli/specky.mjs workflow run <workflow-id>       --param period=weekly       --param audience=product

The command queues a real workflow execution and returns its id. It does not wait for a long-running workflow to finish in the shell; inspect the run in Specky after it has been picked up.

A complete example

Every Monday, a CI job can search for new onboarding signals, capture a release note, and queue a workspace workflow for a weekly briefing. The shell job stays small because the intelligence and permissions remain in Specky:

node ./cli/specky.mjs search "onboarding" --limit 50 --json > onboarding.json
node ./cli/specky.mjs workflow run <workflow-id> --param period=weekly --json

If the API returns an error, the command exits non-zero and prints the server's actual error. Missing keys, revoked keys, invalid payloads, workspace limits, and unavailable workflows are not silently presented as success.

What the CLI does not claim yet

The current client covers search, recent signals, documents, capture, and workflow runs. It does not claim local folder synchronization, a Homebrew formula, or a published npm package until those distribution paths are actually released.