Getting Started

Installation

Install the CLI globally via npm:

npm install -g @specrun/cli

Or via Homebrew:

brew install spichen/tap/specrun

Verify the installation:

specrun --version

Create Your First Agent

Scaffold a new project:

specrun init my-agent

This creates:

my-agent/
├── flow.json      # Your workflow definition
└── tools/
    └── example_tool.sh   # A sample tool

Run the Workflow

cd my-agent
specrun run flow.json --tools-dir tools

You should see output showing the flow executing through each node.

Interactive Chat Mode

For debugging and exploration, use chat mode:

specrun run flow.json --tools-dir tools --chat

This starts a persistent multi-turn conversation with your agent.

Validate a Spec

Check your workflow for errors before running:

specrun validate flow.json --tools-dir tools

This validates the spec schema, compiles the graph, and checks that all referenced tools exist.