CLI Examples

Real-world workflow examples demonstrating how to use the funcspec CLI effectively.

Setting Up a New Project

Starting from scratch with a new project:

# 1. Authenticate
funcspec auth login
# Enter your API key: ****
# Authenticated as: alice@acme.com (Acme Corp)

# 2. Create the project
funcspec projects create "Order Management" \
  --description "Order lifecycle from placement to fulfillment"
# Created project: order-management

# 3. Set it as default to avoid typing --project every time
funcspec projects set-default order-management

# 4. Create your first functional specs
funcspec items create \
  --type functional \
  --title "Place an order" \
  --description "Customers can add items to cart and complete checkout." \
  --priority high \
  --tags "orders,checkout"
# Created F-1: Place an order

funcspec items create \
  --type functional \
  --title "Order confirmation email" \
  --description "Customers receive an email confirmation after placing an order." \
  --priority high \
  --tags "orders,email"
# Created F-2: Order confirmation email

funcspec items create \
  --type functional \
  --title "Order status tracking" \
  --description "Customers can view the current status of their orders." \
  --priority medium \
  --tags "orders"
# Created F-3: Order status tracking

# 5. Check your project stats
funcspec stats
# Spec Items
#   Total: 3 (3 functional, 0 technical)
#   Draft: 3

Importing an Existing Spec

Import a set of spec items from a JSON file using the bulk create API:

# specs-import.json
cat > specs-import.json << 'EOF'
{
  "items": [
    { "title": "User registration", "type_of": "functional", "priority": "high", "tags": ["auth"] },
    { "title": "Email verification", "type_of": "functional", "priority": "high", "tags": ["auth", "email"] },
    { "title": "Password strength validation", "type_of": "functional", "priority": "medium", "tags": ["auth"] },
    { "title": "OAuth login (Google)", "type_of": "functional", "priority": "medium", "tags": ["auth", "oauth"] }
  ]
}
EOF

# Import via API
curl -X POST https://funcspec.net/api/v1/projects/42/spec/items/bulk \
  -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d @specs-import.json

# {
#   "data": {
#     "created": 4,
#     "items": [
#       { "id": 1, "permalink": "F-1", "title": "User registration" },
#       ...
#     ]
#   }
# }

After import, transition items from draft to accepted:

for permalink in F-1 F-2 F-3 F-4; do
  funcspec items transition $permalink --state accepted
  echo "Accepted $permalink"
done

Running AI Review on All Items

Review your entire specification for coverage and quality:

# Queue a review for all accepted items
funcspec ai review-all --project order-management

# Progress: ████████████░░░░░░░░ 12/20 complete...
# Done. 20 items reviewed.

# See which items need work
funcspec items list --state accepted \
  | grep -v "pass" # or use --format json and jq

# Better: use JSON format and jq to filter
funcspec items list --state accepted --format json \
  | jq '.data[] | select(.review_verdict == "needs_work" or .review_verdict == "fail") | .permalink'
# "F-3"
# "F-7"
# "F-11"

# Review each problem item in detail
funcspec ai review F-3

Generating Tech Specs from Functional Requirements

For each accepted functional spec, generate technical implementation specs:

# Generate tech specs for a functional spec
funcspec ai generate F-1

# Proposals:
#   0: Order model and database schema
#   1: Cart management service
#   2: Checkout controller with payment integration
#   3: Order confirmation job (async email)
#   4: Inventory deduction on order placement
#
# Create which? (0-4, comma-separated, or 'all'): all
# Created T-1: Order model and database schema
# Created T-2: Cart management service
# Created T-3: Checkout controller with payment integration
# Created T-4: Order confirmation job (async email)
# Created T-5: Inventory deduction on order placement

# Link the technical specs to the functional requirement
funcspec edges link T-1 F-1
funcspec edges link T-2 F-1
funcspec edges link T-3 F-1
funcspec edges link T-4 F-1
funcspec edges link T-5 F-1

# Check coverage
funcspec stats
# ...
# AI Reviews
#   Impact coverage: 85%  (17/20 functional specs have technical coverage)

Exporting Documentation

Export your specifications for sharing with stakeholders:

# Export as PDF for stakeholders
funcspec export --format pdf -o "order-management-specs-$(date +%Y%m%d).pdf"

# Export as Markdown for the repo wiki
funcspec export --format markdown -o docs/specifications.md

# Export as JSON for programmatic use
funcspec export --format json -o specs.json

Scripting with --format json and jq

The --format json flag makes the CLI composable with standard Unix tools:

# List all items with failed review, output as CSV
funcspec items list --format json | \
  jq -r '.data[] | select(.review_verdict == "fail") |
    [.permalink, .title, .review_verdict] | @csv'

# "F-3","Order status tracking","fail"
# "F-11","Return and refund flow","fail"

# Count items by state
funcspec items list --per 1 --format json | \
  jq '.meta.total'

# Get permalinks of all unreviewed accepted items
funcspec items list --state accepted --format json | \
  jq -r '.data[] | select(.has_review == false) | .permalink'

# Bulk-transition all draft items to inbox
funcspec items list --state draft --format json | \
  jq -r '.data[].permalink' | \
  xargs -I{} funcspec items transition {} --state inbox

# Export a summary table of implementation status
funcspec items list --type technical --state accepted --format json | \
  jq -r '.data[] | [.permalink, .title, (.implementation_status // "pending")] | @tsv' | \
  column -t

CI/CD Integration Patterns

GitHub Actions — review on PR

Run AI reviews as part of your pull request workflow:

# .github/workflows/spec-review.yml
name: Spec Review

on:
  pull_request:
    branches: [main]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Download funcspec CLI
        run: |
          curl -L https://github.com/narbs/funcspec-cli/releases/latest/download/funcspec-linux-amd64 \
            -o /usr/local/bin/funcspec
          chmod +x /usr/local/bin/funcspec

      - name: Review all specs
        env:
          FUNCSPEC_API_KEY: ${{ secrets.FUNCSPEC_API_KEY }}
        run: |
          funcspec ai review-all --project ${{ vars.FUNCSPEC_PROJECT }}

      - name: Check for failing reviews
        env:
          FUNCSPEC_API_KEY: ${{ secrets.FUNCSPEC_API_KEY }}
        run: |
          FAILING=$(funcspec items list \
            --state accepted \
            --format json | \
            jq '[.data[] | select(.review_verdict == "fail")] | length')

          if [ "$FAILING" -gt "0" ]; then
            echo "::warning ::$FAILING spec item(s) failed AI review. Review them at https://funcspec.net"
          fi

Post-deploy audit

After deploying new code, audit your specs to verify implementation:

# .github/workflows/post-deploy-audit.yml
name: Post-Deploy Spec Audit

on:
  workflow_run:
    workflows: [Deploy]
    types: [completed]

jobs:
  audit:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    steps:
      - name: Install funcspec
        run: |
          curl -L https://github.com/narbs/funcspec-cli/releases/latest/download/funcspec-linux-amd64 \
            -o /usr/local/bin/funcspec
          chmod +x /usr/local/bin/funcspec

      - name: Audit all technical specs
        env:
          FUNCSPEC_API_KEY: ${{ secrets.FUNCSPEC_API_KEY }}
        run: |
          funcspec ai audit-all --project ${{ vars.FUNCSPEC_PROJECT }}
          echo "Audit complete. Review results at https://funcspec.net"

Snapshot before release

Create a snapshot before each release tag for future reference:

- name: Snapshot specs
  env:
    FUNCSPEC_API_KEY: ${{ secrets.FUNCSPEC_API_KEY }}
  run: |
    VERSION=${{ github.ref_name }}  # e.g., v2.1.0
    funcspec snapshots create \
      --project ${{ vars.FUNCSPEC_PROJECT }} \
      --name "release-${VERSION}"

Comparing Spec Changes Over Time

Use snapshots to track how your spec has evolved:

# Take a snapshot before a major refactor
funcspec snapshots create --name "before-auth-rewrite"
# Created snapshot 8: before-auth-rewrite (75 items)

# ... (make spec changes) ...

# See what changed
funcspec snapshots diff 8

# + F-26: Passwordless login via magic link  [added]
# + F-27: OAuth login via GitHub             [added]
# ~ F-2:  Password reset                     [description changed]
# ~ F-4:  Two-factor authentication          [state: draft → accepted]
# - F-8:  Legacy LDAP integration            [deleted]

Interactive Triage Session

Quickly triage all inbox items:

# List what's in the inbox
funcspec items list --state inbox

# F-22  Guest checkout flow      functional  inbox  medium
# F-23  Bulk order import        functional  inbox  low
# F-24  Return authorization     functional  inbox  high

# Triage one by one
funcspec items show F-22
funcspec items transition F-22 --state accepted

funcspec items show F-23
funcspec items transition F-23 --state rejected

funcspec items show F-24
funcspec items transition F-24 --state accepted

# Verify inbox is clear
funcspec items list --state inbox
# (no items)