CLI Commands Reference¶

Complete reference for all funcspec CLI commands.

Global Flags¶

These flags work with every command:

Flag	Description
`--project <slug>`	Project to operate on (overrides `default_project` config)
`--format <fmt>`	Output format: `table` (default), `json`, `yaml`
`--verbose`	Enable verbose output
`--debug`	Enable debug output (very detailed, includes HTTP requests)
`--profile <name>`	Use a named config profile
`--help`, `-h`	Show help for any command
`--version`	Print CLI version

auth¶

Manage CLI authentication.

Authenticate with an API key.

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

auth logout¶

Remove stored credentials.

funcspec auth logout
# Logged out.

auth status¶

Show current authentication state.

funcspec auth status
# Authenticated as: alice@acme.com
# Organization:     Acme Corp
# Plan:             Pro
# API key:          fs_live_...abc1 (last 4 chars)

config¶

Manage CLI configuration.

config set¶

Set a configuration value.

funcspec config set api_key "fs_live_abc123..."
funcspec config set base_url "https://funcspec.yourcompany.com"
funcspec config set default_format "json"
funcspec config set default_project "payments-service"

config get¶

Get a configuration value.

funcspec config get base_url
# https://funcspec.net

config list¶

Show all configuration values.

funcspec config list
# api_key          = fs_live_...abc1
# base_url         = https://funcspec.net
# default_format   = table
# default_project  = payments-service

config set-profile¶

Create or switch to a named profile.

# Create a profile
funcspec config set-profile production \
  --api-key "fs_live_prod-key" \
  --base-url "https://funcspec.net"

# Switch active profile
funcspec config set-profile production

projects¶

Manage projects.

projects list¶

List all accessible projects.

funcspec projects list

# Project             Slug                 Org         Items
# ─────────────────────────────────────────────────────────────
# Payments Service    payments-service     acme         75
# Auth System         auth-system          acme         42
# Mobile App          mobile-app           acme         31

projects show¶

Show details for a project.

funcspec projects show payments-service

# Name:        Payments Service
# Slug:        payments-service
# Org:         Acme Corp
# Description: Stripe integration and billing workflows
# Items:       75 (24 functional, 51 technical)
# Accepted:    62 (83%)
# GitHub:      acme/payments-service

projects set-default¶

Set the default project for subsequent commands.

funcspec projects set-default payments-service
# Default project set to: payments-service

Equivalent to funcspec config set default_project payments-service.

items¶

Manage spec items.

items list¶

List spec items in a project.

funcspec items list --project payments-service

# ID    Permalink  Title                          Type        State     Priority
# ───────────────────────────────────────────────────────────────────────────────
# 15    F-1        User authentication            functional  accepted  high
# 16    F-2        Password reset                 functional  accepted  high
# 28    T-1        Auth controller                technical   accepted  high

Flags

Flag	Description
`--type <type>`	Filter: `functional` or `technical`
`--state <state>`	Filter: `draft`, `inbox`, `accepted`, `rejected`
`--tag <tag>`	Filter by tag
`--search <query>`	Full-text search
`--impl-status <s>`	Filter by implementation status
`--parent <permalink>`	Show children of a specific item
`--sort <field>`	Sort by field; prefix `-` for descending
`--page <n>`	Page number
`--per <n>`	Items per page

items show¶

Show full details of a spec item.

funcspec items show F-1

# Permalink:   F-1
# Title:       User authentication
# Type:        functional
# State:       accepted
# Priority:    high
# Tags:        auth, security
# Version:     4
# Created:     2026-01-10
# Updated:     2026-03-15
#
# Description:
# Users can log in using their registered email address and password...

items create¶

Create a new spec item.

funcspec items create \
  --project payments-service \
  --type functional \
  --title "Guest checkout flow" \
  --description "Customers can complete a purchase without creating an account." \
  --priority high \
  --tags "checkout,payments"

# Created F-25: Guest checkout flow

Flags

Flag	Description
`--type <type>`	`functional` or `technical` (required)
`--title <title>`	Item title (required)
`--description <text>`	Description text
`--priority <p>`	`low`, `medium`, `high`, `critical`
`--tags <tags>`	Comma-separated tags
`--parent <permalink>`	Parent item
`--state <state>`	Initial state (default: `draft`)

items update¶

Update an existing spec item.

funcspec items update F-25 \
  --title "Guest and account checkout" \
  --priority critical

items edit¶

Open the item description in $EDITOR for editing.

funcspec items edit F-25
# Opens description in vim/nano/etc.
# Saves on exit.

items delete¶

Delete a spec item.

funcspec items delete F-25
# Are you sure? This cannot be undone. [y/N]: y
# Deleted F-25.

Use --confirm to skip the confirmation prompt (useful in scripts).

items transition¶

Change an item's state.

funcspec items transition F-25 --state accepted
funcspec items transition F-26 --state rejected

items transition-impl¶

Change an item's implementation status.

funcspec items transition-impl T-12 --status implemented
funcspec items transition-impl T-13 --status in_progress

ai¶

Run AI operations on spec items.

ai review¶

Run AI review on a single item.

funcspec ai review F-1

# Reviewing F-1...
#
# Coverage Score: 72/100
# Verdict:        needs_work
#
# Gaps:
#   • No error handling for invalid email addresses
#   • Password reset token expiry not mentioned
#
# Suggestions:
#   • Specify token validity window (recommend 1 hour)
#   • Define behavior on expired token use

ai review-all¶

Review all accepted items in a project.

funcspec ai review-all --project payments-service

# Queued 62 items for review.
# Progress: ████████░░░░░░░░░░░░ 18/62 complete...

ai improve¶

Generate an AI improvement proposal for a spec item.

funcspec ai improve F-1

# Generating proposal for F-1...
#
# Proposed changes:
# + ## Requirements
# + - Email addresses are normalized to lowercase
# + - Accounts are locked after 5 failed attempts
# ...
#
# Accept this proposal? [y/N]: y
# Proposal accepted. F-1 updated.

Use --no-interactive to save the proposal without prompting (accept/reject separately).

ai accept¶

Accept a pending improvement proposal.

funcspec ai accept F-1
# Proposal accepted. F-1 updated.

ai reject¶

Reject a pending improvement proposal.

funcspec ai reject F-1
# Proposal rejected.

ai apply-all¶

Accept all pending proposals in a project.

funcspec ai apply-all --project payments-service
# Applied 18 proposals.

ai generate¶

Generate technical spec proposals from a functional spec.

funcspec ai generate F-1

# Generating tech specs for F-1...
#
# Proposals:
#   0: User model authentication fields
#   1: Authentication controller (sessions)
#   2: Account lockout service
#   3: Session management middleware
#
# Create which? (0-3, comma-separated, or 'all'): 0,1,2
# Created T-15: User model authentication fields
# Created T-16: Authentication controller (sessions)
# Created T-17: Account lockout service

ai audit¶

Run a code audit for a technical spec.

funcspec ai audit T-15

# Auditing T-15 against acme/payments-service...
#
# Status: partial
#
# Findings:
#   ✓ implemented  User model found at app/models/user.rb
#   ⚠ divergence   Token expiry is 24h in code; spec requires 1h
#   ✗ missing      Single-use flag (used_at) not in schema

ai audit-all¶

Audit all accepted technical specs.

funcspec ai audit-all --project payments-service
# Queued 51 items for audit.

edges¶

Manage dependency edges between spec items.

edges list¶

List dependency edges for the project.

funcspec edges list --project payments-service

# Source   Target   Relationship
# ───────────────────────────────
# T-15     F-1      implements
# T-16     F-1      implements
# T-17     F-1      implements

edges link¶

Create a dependency edge.

funcspec edges link T-15 F-1
# Created edge: T-15 → F-1

edges unlink¶

Delete a dependency edge.

funcspec edges unlink T-15 F-1
# Deleted edge: T-15 → F-1

search¶

Full-text search across spec items.

funcspec search "password reset" --project payments-service

# F-2   Password reset flow           functional  accepted
# T-9   PasswordResetToken model      technical   accepted
# T-10  PasswordResetMailer           technical   accepted

stats¶

Show project statistics.

funcspec stats --project payments-service

# Spec Items
#   Total:       75  (24 functional, 51 technical)
#   Accepted:    62
#   Draft:        5
#   Inbox:        3
#   Rejected:     5
#
# Implementation (Technical)
#   Pending:     18
#   In Progress: 12
#   Implemented: 28
#   Verified:     4  (not_applicable: 1)
#
# AI Reviews
#   Reviewed:    58 / 75
#   Pass:        42
#   Needs Work:  14
#   Fail:         2
#   Avg Score:   81

export¶

Export project documentation.

# Export as Markdown
funcspec export --project payments-service --format markdown -o specs.md

# Export as JSON
funcspec export --project payments-service --format json -o specs.json

# Export as PDF
funcspec export --project payments-service --format pdf -o specs.pdf

# Export as HTML
funcspec export --project payments-service --format html -o specs.html

Flags

Flag	Description
`--format <fmt>`	`markdown`, `json`, `html`, `pdf` (required)
`-o <file>`	Output file path (default: stdout)

snapshots¶

Snapshots capture the full state of a project's spec items at a point in time, enabling diff and restore.

snapshots list¶

funcspec snapshots list --project payments-service

# ID    Name                Created              Items
# ───────────────────────────────────────────────────
# 5     pre-v2-launch       2026-03-01T09:00:00  72
# 4     after-auth-review   2026-02-15T14:30:00  68
# 3     baseline            2026-01-15T12:00:00  45

snapshots create¶

funcspec snapshots create --project payments-service --name "pre-v2-launch"
# Created snapshot 5: pre-v2-launch (72 items)

snapshots show¶

funcspec snapshots show 5 --project payments-service
# Shows all spec items as they were at snapshot time.

snapshots diff¶

Compare the current project state (or two snapshots) to see what changed.

# Diff current state against snapshot 5
funcspec snapshots diff 5 --project payments-service

# Diff two snapshots
funcspec snapshots diff 3 5 --project payments-service

# + F-23: Guest checkout flow  [added]
# ~ F-2:  Password reset        [description changed]
# - F-8:  Legacy SSO            [deleted]

snapshots restore¶

Restore a project to the state captured in a snapshot.

Warning

Restore replaces all current spec items with the snapshot contents. This cannot be undone. Consider taking a snapshot of the current state before restoring.

funcspec snapshots restore 5 --project payments-service
# Restore snapshot 5 (pre-v2-launch)? This will overwrite current state. [y/N]: y
# Restored. 72 items.

snapshots delete¶

funcspec snapshots delete 3 --project payments-service --confirm
# Deleted snapshot 3.

view¶

Open a spec item or project in your browser.

# Open a spec item in browser
funcspec view F-1

# Open the project dashboard in browser
funcspec view --project payments-service

CLI Commands Reference¶

Global Flags¶

auth¶

auth login¶

auth logout¶

auth status¶

config¶

config set¶

config get¶

config list¶

config set-profile¶

projects¶

projects list¶

projects show¶

projects set-default¶

items¶

items list¶

items show¶

items create¶

items update¶

items edit¶

items delete¶

items transition¶

items transition-impl¶

ai¶

ai review¶

ai review-all¶

ai improve¶

ai accept¶

ai reject¶

ai apply-all¶

ai generate¶

ai audit¶

ai audit-all¶

edges¶

edges list¶

edges link¶

edges unlink¶

search¶

stats¶

export¶

snapshots¶

snapshots list¶

snapshots create¶

snapshots show¶

snapshots diff¶

snapshots restore¶

snapshots delete¶

view¶