@directive-run/cli

CLI for Directive – project scaffolding, system introspection, AI coding rules, and more.

Installation

# Run directly (no install needed)
npx directive --help

# Or install globally
npm install -g @directive-run/cli

The binary is aliased as both directive and dr.

Commands

directive init

Interactive project scaffolding wizard. Creates a starter module + system entry file.

directive init                          # Interactive wizard
directive init --template counter       # Skip prompts, use counter template
directive init --template auth-flow     # Constraints + resolvers starter
directive init --template ai-orchestrator  # AI agent starter
directive init --no-interactive         # Defaults only (counter template)
directive init --dir ./my-project       # Target directory

Templates:

• counter – Minimal: schema, init, derive, events
• auth-flow – Login flow with constraints, resolvers, retry, and effects
• ai-orchestrator – Agent module with memory, guardrails, and streaming

directive new module <name>

Generate a typed module file.

directive new module auth               # Full module (all sections)
directive new module auth --minimal     # Schema + init only
directive new module auth --with derive,constraints,resolvers
directive new module auth --dir ./src/modules

directive new orchestrator <name>

Generate an AI orchestrator module with @directive-run/ai.

directive new orchestrator my-agent
directive new orchestrator my-agent --dir ./src

directive inspect <file>

Load a Directive system and print structured overview: facts, constraints, resolvers, unmet requirements, inflight status.

directive inspect src/main.ts           # Pretty-printed table
directive inspect src/main.ts --json    # JSON output
directive inspect src/main.ts --module auth  # Specific module

Warns on unresolved requirements (no matching resolver).

directive explain <file> [requirement-id]

Explain why a requirement exists. Wraps system.explain() for terminal use.

directive explain src/main.ts           # List all requirements + status
directive explain src/main.ts req-123   # Detailed explanation for one

directive graph <file>

Visual dependency graph: facts → constraints → requirements → resolvers.

directive graph src/main.ts             # HTML output, opens in browser
directive graph src/main.ts --ascii     # Terminal-only box-drawing output
directive graph src/main.ts --no-open   # Generate HTML but don't open
directive graph src/main.ts --output graph.html

directive doctor

Non-interactive health check for project setup.

directive doctor                        # Check current directory
directive doctor --dir ./my-project     # Check specific directory

Checks:

• @directive-run/core installed
• Package version compatibility
• TypeScript 5.3+ with strict: true and correct moduleResolution
• No duplicate Directive instances in node_modules
• AI rules freshness (if installed)

Exits non-zero on failures.

directive ai-rules init

Install AI coding rules for your AI coding assistant.

directive ai-rules init                 # Interactive – detect tools, prompt
directive ai-rules init --tool cursor   # Specific tool
directive ai-rules init --force         # Overwrite existing files
directive ai-rules init --merge         # Update Directive section only
directive ai-rules init --dir ./project

directive ai-rules update

Regenerate all existing rule files to the latest knowledge version.

directive ai-rules update
directive ai-rules update --dir ./project

directive ai-rules check

Validate rules are current. Exits non-zero if stale – designed for CI.

directive ai-rules check
directive ai-rules check --dir ./project

directive examples list

Browse available examples from @directive-run/knowledge.

directive examples list                 # All examples, grouped by category
directive examples list --filter ai     # Filter by category or name

directive examples copy <name>

Extract an example to your project. Rewrites workspace imports to published package names.

directive examples copy counter
directive examples copy auth-flow --dest ./src/examples

directive replay <timeline.json>

Re-dispatch a serialized @directive-run/timeline JSON dump against a fresh system. Designed for the prod-error-to-local-repro flow: production captures the last N seconds of timeline frames via serializeTimeline(), ships the JSON to your bug tracker, and an engineer pastes the path into replay.

directive replay bug-1234.json --system src/app/system.ts
# ✓ replay complete: 47 dispatched / 18 skipped

directive replay bug-1234.json --system src/system.ts --json
# {"dispatched": 47, "skipped": 18, "truncated": 0}

directive replay bug-1234.json --system src/system.ts --max-frames 10000

The --system <path> file must export a started Directive system as either a default export or a named system export. Same shape as inspect / graph / explain.

Requires @directive-run/timeline as a peer dep: install it with npm install --save-dev @directive-run/timeline.

directive bisect <timeline.json>

Binary-search a recorded timeline for the first frame whose inclusion flips a user-supplied assertion from passing to failing — git-bisect, but over ObservationEvent frames.

directive bisect bug-1234.json \
  --system test/bisect-system.ts \
  --assert 'facts.count >= 0'
# ✓ bisect complete: first failing frame is #47 (fact.change)

The --system <path> file must export a factory (not a started instance — bisect calls the factory once per midpoint to keep each replay hermetic). Looks for createSystem / systemFactory / default exports, in that order. The factory must return a started system:

// test/bisect-system.ts
export function createSystem() {
  const sys = makeSys({ module: counterModule });
  sys.start();
  return sys;
}

The --assert <expression> is evaluated as JS with facts and system in scope. Truthy = good prefix; falsy = bad prefix. Bisect locates the smallest bad prefix.

SECURITY: --assert runs as JavaScript in the CLI process. Only pass expressions from sources you trust. Don't paste expressions from untrusted issues / Slack / third parties.

Options: --max-frames <n> (default 100,000), --no-determinism-check (skip the replay-twice gate), --json, --verbose.

Exit codes: 0 (no failure to bisect / fails-on-empty), 2 (bisect found a frame OR refused due to non-determinism), 1 (CLI error).

directive timeline diff <a.json> <b.json>

Semantic causal-graph diff between two serialized timelines. Not a textual JSON diff — per-category deltas (frame counts, constraint fires, mutation kinds, resolver runs, new errors).

directive timeline diff baseline.json regression.json
# Frames:           23 → 31  (+8)
# Constraint fires:
#   loadOnLoading                    1 →    4  (+3)
# Mutations:
#   submit                           2 →    3  (+1)
# Resolver runs:
#   loader              starts 1→2 (+1)  completes 1→1 ( 0)  errors 0→1 (+1)
# New errors:
#   b-only  frame #15  resolver.error 'loader'  "timeout"

directive timeline diff a.json b.json --json | jq .constraintFires

Exit codes: 0 (identical), 2 (differences found, CI-gate friendly), 1 (CLI error).

Supported AI Tools

| Tool | Output File | |------|-------------| | Cursor | .cursorrules | | Cline | .clinerules | | GitHub Copilot | .github/copilot-instructions.md | | Windsurf | windsurf.md | | Claude Code | CLAUDE.md | | LLMs.txt | llms.txt |

Programmatic API

import { getTemplate, loadSystem, detectTools } from "@directive-run/cli";

// Generate AI rules content
const cursorRules = getTemplate("cursor");

// Load a Directive system from a TS file
const system = await loadSystem("./src/main.ts");
const inspection = system.inspect();

// Detect AI coding tools in a directory
const tools = detectTools("./my-project");

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.