pickaxe-cli

Standalone workspace for the Pickaxe CLI.

This repo is initialized around the Alpha surface from the product plan:

• workspace API key auth
• local project initialization
• doctor, remote whoami, and workspace discovery
• sync, deploy, and remote builder session commands
• a small SDK boundary for the current /v1/studio endpoints

Install from npm after publishing:

npm install -g @pickaxe/pickaxe-cli
pickaxe --help

Or run without a global install:

npx @pickaxe/pickaxe-cli --help

Quick Start

Published package:

npm install -g @pickaxe/pickaxe-cli
pickaxe --help

Local development:

pnpm link --global
pickaxe
pnpm cli
pnpm cli --help
pnpm cli init
pnpm cli doctor
pnpm cli auth login --api-key studio-...
pnpm cli whoami
pnpm cli workspace list
pnpm cli list
pnpm cli create
pnpm cli build "make me a pricing copilot"
pnpm cli review
pnpm cli apply
pnpm cli test --message "hello"

Interactive terminals can now fill in missing builder/test inputs for you:

• pickaxe build, pickaxe improve, pickaxe plan, and pickaxe chat prompt for missing text and can open a live Pickaxe picker when no id is available.
• pickaxe test can prompt for a test message and choose a live Pickaxe when --id is omitted.
• on one-shot builder backends, pickaxe build now renders the preview and then tells you what to do next instead of failing into missing session flows.

Current Layout

pickaxe-cli/
  package.json
  pnpm-workspace.yaml
  packages/
    sdk/
      src/
    cli/
      src/
      bin/
  docs/
  fixtures/

Current Command Status

Implemented now:

• pickaxe auth login --api-key
• pickaxe auth logout
• pickaxe whoami
• pickaxe workspace list
• pickaxe list
• pickaxe create
• pickaxe build
• pickaxe improve
• pickaxe plan
• pickaxe chat
• pickaxe review
• pickaxe apply
• pickaxe init
• pickaxe doctor
• pickaxe pull --id <pickaxe-id> [--force]
• pickaxe diff
• pickaxe push
• pickaxe docs add
• pickaxe docs list
• pickaxe docs remove
• pickaxe history
• pickaxe memory <list|create|get|update|user>
• pickaxe users <list|get|invite|create|update>
• pickaxe access-groups <list|get|create|update|assign|remove>
• pickaxe deploy create
• pickaxe deploy list
• pickaxe test

Notes:

• pull, diff, push, and deploy create use the current /v1/studio endpoints only.
• list, workspace list, whoami, deploy list, test, and the builder commands use the deployed Studio discovery and builder endpoints.
• create is the current CLI orchestration flow:
  • guided chatbot setup in the terminal
  • writes or updates the local project in the current folder
  • pushes the Pickaxe remotely
  • can create a deployment
  • can create or attach an access group to that deployment
• build supports both backend shapes:
  • session-capable builder backends return a builderSessionId and persist it in .pickaxe/state.json
  • older one-shot build backends return a summary/change-set preview only, and the CLI stops cleanly after rendering it
• in interactive terminals, create, build, improve, plan, chat, and live test prompt for missing text and can guide you to a live Pickaxe when no id is available or the tracked id is stale.
• improve, plan, chat, review, apply, and test --draft require a session-capable backend. On one-shot environments, the CLI prints a clear “backend only supports one-shot build” message.
• if the tracked pickaxe.id is stale and no longer exists remotely, the CLI now tells you to relink with pickaxe list plus --id <pickaxe-id> instead of surfacing a raw backend error.
• pull still needs an explicit pickaxe id unless the local project already tracks one in pickaxe.yaml or .pickaxe/state.json.
• pull refuses to overwrite divergent local pickaxe.yaml or prompt files unless you pass --force.
• publish from the repo root with npm publish --access public once the @pickaxe scope permissions are configured.

Status Graph

flowchart TD
    A["pickaxe cli status today"] --> B["works today"]
    A --> C["works with caveats"]
    A --> D["still needs work"]

    B --> B1["pickaxe auth login --api-key"]
    B --> B2["pickaxe auth logout"]
    B --> B3["pickaxe init"]
    B --> B4["pickaxe doctor"]
    B --> B5["pickaxe whoami"]
    B --> B6["pickaxe workspace list"]
    B --> B7["pickaxe list"]
    B --> B8["pickaxe memory <list|create|get|update|user>"]
    B --> B9["pickaxe users <list|get|invite|create|update>"]
    B --> B10["pickaxe access-groups <list|get|create|update|assign|remove>"]
    B --> B11["pickaxe deploy list"]

    C --> C1["pickaxe build<br/>works on both session and one-shot backends"]
    C --> C2["pickaxe improve|plan|chat<br/>requires session-capable backend"]
    C --> C3["pickaxe review|apply|test --draft<br/>requires stored builder session"]
    C --> C4["pickaxe pull --id <pickaxe-id><br/>needs api key + explicit id or tracked local id"]
    C --> C5["pickaxe diff [--id] [--verbose]<br/>needs api key"]
    C --> C6["pickaxe push [--id] [--dry-run]<br/>needs api key"]
    C --> C7["pickaxe docs add|list|remove<br/>needs api key"]
    C --> C8["pickaxe history [--id ...]<br/>needs api key"]
    C --> C9["pickaxe deploy create --type ...<br/>needs api key"]
    C --> C10["pickaxe test --message ...<br/>depends on backend support"]

    D --> D1["explain command"]
    D --> D2["actions and mcps manifest parity"]

    classDef good fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    classDef partial fill:#fff8e1,stroke:#f9a825,color:#5d4037;
    classDef todo fill:#ffebee,stroke:#c62828,color:#7f1d1d;

    class B,B1,B2,B3,B4,B5,B6,B7,B8,B9,B10,B11 good;
    class C,C1,C2,C3,C4,C5,C6,C7,C8,C9,C10 partial;
    class D,D1,D2 todo;

For this pass, local auth is stored in ~/.pickaxe/config.json as a temporary fallback until keychain support lands.