Skip to main content

CLI Overview

The HarnSpec CLI provides a complete toolkit for managing specifications in your project. Whether you're a developer working directly or an AI agent automating workflows, the CLI offers efficient commands for every stage of the spec lifecycle.

For Human Developers​

The CLI gives you command-line control over your specs:

  • Create and manage specs with simple commands
  • Search and discover related work instantly
  • Track progress with visual boards and metrics
  • Validate quality to maintain spec health

Quick example workflow:

# Create new spec
harnspec create auth-refactor --tags security

# Start working
harnspec update 042 --status in-progress

# Check project health
harnspec board

# Validate before committing
harnspec validate

For AI Agents​

The CLI is designed as a toolset for AI agents, enabling them to:

  • Discover context - Search and retrieve relevant specs to answer questions
  • Track decisions - Access past architectural choices and rationale
  • Manage work - Create, update, and link specs programmatically
  • Maintain quality - Validate spec structure and token counts

AI agents can use HarnSpec CLI commands directly as tools:

# Agent searches for relevant context
harnspec search "authentication decision"

# Agent retrieves specific spec
harnspec view 042

# Agent checks dependencies
harnspec deps 042

# Agent updates status after implementation
harnspec update 042 --status complete

AI Agent Ready: The HarnSpec CLI is designed to be easily used by AI agents as a toolset, providing structured output and powerful search capabilities.

Command Categories​

The CLI organizes commands into logical groups:

Creating & Managing​

Core operations for spec lifecycle:

  • create - Start new specs
  • update - Modify status, priority, tags
  • view - Read spec content
  • open - Edit in your preferred editor

Learn more: Creating & Managing Specs

Finding Specs​

Discover and navigate specifications:

  • list - View all specs with filters
  • search - Find by content or metadata
  • deps - Explore relationships

Learn more: Finding Specs

Project Management​

Track health and validate quality:

  • board - Visual Kanban view
  • stats - Project metrics
  • validate - Check spec quality

Learn more: Project Management and Validation

Core Principles​

The CLI design follows HarnSpec's First Principles:

  1. Context Economy - Commands help manage token budgets (tokens, validate)
  2. Signal-to-Noise - Quick access to relevant information (search, deps)
  3. Intent Over Implementation - Focus on what and why, not just how
  4. Bridge the Gap - Works for both humans and AI agents
  5. Progressive Disclosure - Simple by default, powerful when needed

Quick Reference​

Most common commands:

harnspec create <name>           # Create new spec
harnspec list                    # View all specs
harnspec search "query"          # Find relevant specs
harnspec view <spec>             # Read spec content
harnspec update <spec> --status  # Update status
harnspec board                   # Visual overview
harnspec validate                # Check quality

Get help anytime:

harnspec --help                  # All commands
harnspec <command> --help        # Command details

Integration Points​

Version Control​

HarnSpec plays well with Git:

  • Specs are plain markdown files
  • All changes are traceable
  • Easy to review in PRs

CI/CD​

Automate validation:

# GitHub Actions example
- run: harnspec validate

Editors​

Open specs in your preferred editor:

harnspec open 042

AI Tools​

  • Direct CLI access - Agents can call commands
  • Agent Skills - Domain-specific guidance for AI agents via SKILL.md
  • Search integration - Semantic memory across sessions

Best Practices​

For Humans:

  • Start your day with harnspec board
  • Use harnspec search instead of grep
  • Validate before committing
  • Keep specs under 3,500 tokens

For AI Agents:

  • Search before creating new specs
  • Check dependencies before starting work
  • Update status after implementation
  • Use harnspec deps for context

Next Steps​

Dive into specific workflows:

  1. Creating & Managing Specs - Master basic operations
  2. Finding Specs - Learn search and discovery
  3. Project Management - Track project health
  4. Validation - Ensure spec quality

Reference: See CLI Reference for complete command documentation.

Remember: The CLI is a tool for both human developers and AI agents. Whether you're typing commands or an AI is executing them, the goal is the same: maintain clear, actionable specifications that drive development forward.