ShapeUp CLI

Command-line interface for ShapeUp, the Shape Up methodology platform. Works as a standalone tool and with any AI agent that can execute shell commands.

Zero dependencies — pure Ruby stdlib.

Clone the repo and add to your PATH:

git clone https://github.com/shapeup-cc/shapeup-cli ~/.shapeup-cli

Add to ~/.zshrc (or ~/.bashrc):

export PATH="$HOME/.shapeup-cli/bin:$PATH"

Verify:

shapeup version

# Authenticate (opens browser for OAuth)
shapeup login

# Set your default organisation
shapeup orgs
shapeup config set org "Your Org"

# You're ready
shapeup me              # Show my work
shapeup pitches list    # List pitches
shapeup pitch 42        # Show pitch details
shapeup cycles          # List cycles

Auth:       login, logout
Discovery:  orgs, commands, config
Pitches:    pitches list/show, pitch <id>
Cycles:     cycles, cycle show <id>
Scopes:     scopes list/create/update
Tasks:      tasks list, todo "...", done <id>
My Work:    me, my-work
Search:     search "query"
Setup:      setup claude/cursor/project

Append to any command:

shapeup pitches list --json
shapeup me --md
shapeup cycle show 5 --agent
shapeup pitches list | jq '.data'       # auto-JSON when piped
shapeup tasks list --pitch 42 --ids-only | xargs -I{} shapeup done {}

The CLI is designed for AI agent use. Agents can:

1. Discover commands via structured introspection:

   shapeup --agent --help          # All commands
   shapeup --agent --help tasks    # Drill into tasks

2. Chain commands via breadcrumbs in --json output:

   shapeup pitch 42 --json
   # Response includes: breadcrumbs: [{cmd: "shapeup scopes list --pitch 42", ...}]

3. Install skills for automatic triggering:

   shapeup setup claude    # Installs SKILL.md into ~/.claude/skills/
   shapeup setup cursor    # For Cursor
   shapeup setup project   # Per-project (.claude/skills/)

ShapeUp also provides a native MCP server. Agents that support MCP (Claude, Cursor, etc.) can connect directly:

claude mcp add --transport http shapeup https://shapeup.cc/mcp

The CLI and MCP server share the same backend — use whichever fits your agent.

shapeup config set org "Acme Corp"
shapeup config set host https://shapeup.cc

Stored in ~/.config/shapeup/config.json.

shapeup config init "Acme Corp"

Creates .shapeup/config.json in the current directory. The CLI walks up the directory tree looking for this file, so it works from subdirectories too.

Resolution order: --org flag > env var > .shapeup/config.json > global config.

For CI, scripts, or when you don't want to store credentials on disk:

SHAPEUP_TOKEN=abc123 SHAPEUP_ORG=42 shapeup me --json

--org accepts both names and IDs (case-insensitive exact match):

shapeup pitches list --org "Acme Corp"
shapeup pitches list --org 42

The CLI is a thin HTTP client over ShapeUp's MCP server. Every command maps to an MCP tool call via JSON-RPC:

shapeup pitch 42 --json
  → POST https://shapeup.cc/mcp
  → {"jsonrpc":"2.0","method":"tools/call","params":{"name":"show_package","arguments":{"organisation":"1","package":"42"}}}
  ← {ok: true, data: {...}, breadcrumbs: [...]}

Authentication uses OAuth 2.1 with PKCE. Tokens are stored in ~/.config/shapeup/credentials.json.