CLI Examples

Practical examples of using the PlanSpec CLI.

Basic Workflow

1. Create a Plan File

Create a YAML file with your Goal and Plan:

yaml
# my-feature.yaml
apiVersion: planspec.io/v1alpha1
kind: Goal
metadata:
  name: my-feature
  namespace: default
spec:
  description: Implement my new feature
  acceptanceCriteria:
    - description: Feature works as expected
---
apiVersion: planspec.io/v1alpha1
kind: Plan
metadata:
  name: my-feature-plan
  namespace: default
spec:
  description: Implementation plan for my feature
  goalRef:
    name: my-feature
  graph:
    nodes:
      - id: implement
        kind: Task
        description: Implement the feature

2. Validate Your Plan

Validate the file against the PlanSpec schema:

bash
planspec validate -f my-feature.yaml

Output on success:

✓ my-feature.yaml is valid - 1 Goal - 1 Plan with 1 task

Output on error:

✗ my-feature.yaml has errors: - line 15: task 'deploy' references unknown dependency 'build' - line 22: missing required field 'description'

3. Start the Server

Start the PlanSpec server to manage resources:

bash
planspec serve

The server runs on http://localhost:8080 by default.

4. Apply Resources

Apply your plan to the server:

bash
planspec apply -f my-feature.yaml

5. View Resources

Check what's on the server:

bash
# List all plans
planspec get plans

# Get detailed info about a plan
planspec describe plan my-feature-plan

6. Visualize Dependencies

Generate a dependency graph:

bash
planspec graph my-feature-plan --format mermaid

Output:

graph TD implement

Working with Multiple Files

Validate a Directory

bash
planspec validate -d ./plans/

Apply Multiple Files

bash
planspec apply -d ./plans/

Server-Based Workflows

Watch for Changes

Monitor resources in real-time:

bash
planspec watch plans

Edit Resources

Edit a resource directly on the server:

bash
planspec edit plan my-feature-plan

This opens the resource in your $EDITOR.

Compare Local vs Server

See what would change before applying:

bash
planspec diff -f my-feature.yaml

Visualization

Generate Dependency Graph

First, ensure your plan is applied to the server:

bash
planspec apply -f plan.yaml
planspec graph my-plan --format mermaid

Output:

graph TD setup-database --> create-api create-api --> implement-auth implement-auth --> add-tests add-tests --> deploy

Export to DOT Format

bash
planspec graph my-plan --format dot | dot -Tpng -o graph.png

CI/CD Integration

GitHub Actions Example

yaml
name: Validate Plans
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install PlanSpec
        run: cargo install planspec
      - name: Validate
        run: planspec validate -d ./plans/

Pre-commit Hook

bash
#!/bin/sh
# .git/hooks/pre-commit

planspec validate -d ./plans/
if [ $? -ne 0 ]; then
  echo "Plan validation failed"
  exit 1
fi

Using Namespaces

Create a Namespace

bash
planspec create namespace production

Work in a Specific Namespace

bash
# Using flag
planspec get plans -n production

# Using environment variable
export PLANSPEC_NAMESPACE=production
planspec get plans

Connecting to a Remote Server

bash
# Using flag
planspec get plans --server https://planspec.example.com

# Using environment variable
export PLANSPEC_SERVER=https://planspec.example.com
planspec get plans

Next Steps