Commands

Reference for all PlanSpec CLI commands.

Overview

bash

planspec <command> [options]

Resource Management Commands

These commands require a running PlanSpec server (see Running Locally).

apply

Apply resources from a file or directory to the server.

bash

planspec apply -f <file>
planspec apply -d <directory>

Options:

Option	Description
`-f, --file <FILE>`	Path to YAML file to apply
`-d, --directory <DIR>`	Path to directory containing YAML files

Examples:

bash

# Apply a single file
planspec apply -f plan.yaml

# Apply all files in a directory
planspec apply -d ./plans/

get

Get one or more resources from the server.

bash

planspec get <resource-type> [name]

Resource types: goals, plans, capabilities, bindings, executions, all

Examples:

bash

# List all goals
planspec get goals

# Get a specific plan
planspec get plans my-plan

# Get all resources
planspec get all

# Output as JSON
planspec get plans -o json

describe

Show detailed information about a specific resource.

bash

planspec describe <resource-type> <name>

Examples:

bash

# Describe a goal
planspec describe goal my-feature

# Describe a plan
planspec describe plan my-feature-plan

delete

Delete resources from the server.

bash

planspec delete <resource-type> <name>

Examples:

bash

# Delete a plan
planspec delete plan my-plan

# Delete a goal
planspec delete goal my-feature

create

Create a namespace.

bash

planspec create namespace <name>

Examples:

bash

# Create a new namespace
planspec create namespace production

watch

Watch for resource changes in real-time.

bash

planspec watch <resource-type>

Examples:

bash

# Watch all plans
planspec watch plans

# Watch executions
planspec watch executions

diff

Show differences between a file and the server state.

bash

planspec diff -f <file>

Examples:

bash

# Diff a file against server
planspec diff -f plan.yaml

edit

Edit a resource in your default editor ($EDITOR).

bash

planspec edit <resource-type> <name>

Examples:

bash

# Edit a plan
planspec edit plan my-plan

# Edit a goal
planspec edit goal my-feature

graph

Visualize a plan's dependency graph (DAG). Requires a running server.

bash

planspec graph <plan-name>

Options:

Option	Description
`--format <FORMAT>`	Output format (dot, mermaid, json)

Examples:

bash

# Generate Mermaid diagram
planspec graph my-plan --format mermaid

# Generate DOT format and convert to PNG
planspec graph my-plan --format dot | dot -Tpng -o graph.png

Offline Commands

These commands work without a running server.

validate

Validate PlanSpec files against the JSON schema.

bash

planspec validate -f <file>
planspec validate -d <directory>

Options:

Option	Description
`-f, --file <FILE>`	Path to YAML file to validate
`-d, --directory <DIR>`	Path to directory containing YAML files

Examples:

bash

# Validate a single file
planspec validate -f plan.yaml

# Validate all files in a directory
planspec validate -d ./plans/

completions

Generate shell completions for your shell.

bash

planspec completions <shell>

Supported shells: bash, zsh, fish, powershell, elvish

Examples:

bash

# Generate Bash completions
planspec completions bash > ~/.local/share/bash-completion/completions/planspec

# Generate Zsh completions
planspec completions zsh > ~/.zfunc/_planspec

# Generate Fish completions
planspec completions fish > ~/.config/fish/completions/planspec.fish

Server Command

serve

Start the PlanSpec API server.

bash

planspec serve [options]

Options:

Option	Description
`--port <PORT>`	Port to listen on (default: 8080)
`--host <HOST>`	Host to bind to (default: 127.0.0.1)
`--db <PATH>`	Path to SQLite database file
`--reconcile-interval <SECS>`	Interval for reconciliation loop

Examples:

bash

# Start with defaults (localhost:8080)
planspec serve

# Start on a custom port
planspec serve --port 3000

# Start with a specific database
planspec serve --db ./planspec.db

See Running Locally for more details.

Global Options

These options apply to all commands:

Option	Description
`-h, --help`	Show help information
`-V, --version`	Show version number
`-o, --output <FORMAT>`	Output format: json, yaml, table
`-n, --namespace <NS>`	Namespace to use
`--server <URL>`	Server URL to connect to

Environment Variables:

Variable	Description
`PLANSPEC_SERVER`	Server URL (alternative to `--server`)
`PLANSPEC_NAMESPACE`	Default namespace (alternative to `-n`)

Exit Codes

Code	Meaning
0	Success
1	Error

Next Steps

Examples — See commands in action
Running Locally — Start the server