@doctc/arc42

A CLI for validating and querying arc42 software architecture documentation written in the arc42 DSL — Markdown prose with typed :::block fences for structured metadata.

Install

npm install -g @doctc/arc42

Or run without installing:

npx @doctc/arc42 <command>

Getting started

Install the agent skill (works with Claude Code and ~80 other agents):

npx skills add doctoolchain/arc42-language

Then scaffold the first chapter on demand:

arc42 guide chapter 1

Commands

# Validate the workspace — fix all errors before committing
arc42 --dir ./docs validate

# Browse all elements grouped by arc42 chapter
arc42 --dir ./docs get

# Inspect a single element with its 1-hop relationships
arc42 --dir ./docs get bb-catalog-service

# Filter by type
arc42 --dir ./docs get --type decision

# Understand what each validation rule enforces and why
arc42 rules

# JSON output for scripting and agent use
arc42 --dir ./docs validate --format json
arc42 --dir ./docs get --format json

# Discover commands and their purpose
arc42 --help

# Read command-specific usage, options, defaults, and exit behavior
arc42 validate --help
arc42 --help diff

# Review architecture changes
arc42 diff --staged

--dir defaults to $ARC42_DIR or the current directory. Exit codes: 0 = no errors, 1 = validation errors or element not found, 2 = usage error. Use arc42 --help for the command-purpose overview. Help can also precede a command, such as arc42 --help validate.

Validation rules

Run arc42 rules to see each rule with its rationale. The short summary:

• Errors — duplicate ids, unresolved references, circular parent chains, interface pointing at non-building-blocks, missing required attributes
• Warnings — orphaned concepts, isolated building-blocks, stale proposed decisions, blocks without prose, multiple blocks under one heading
• Hints — decisions or solution strategies without quality-goal links, quality goals without decisions or a solution strategy, building-blocks without a technology

The format

Each element lives in its own ## section: heading, prose explaining purpose and rationale, then a typed block as the machine-readable summary.

## Catalog Service

Owns all product data. The only service that writes to the catalog database.
Search results are cached in Redis to meet the p95 latency target.

```arc42
:::building-block
id: bb-catalog-service
title: Catalog Service
technology: Node.js / Express
implements: concept-logging, concept-error-handling
:::
```

See the [bookstore example](https://github.com/oliverjaegle/arc42-language/tree/main/examples/bookstore-backend) for a complete, valid workspace with realistic prose.

## License

MIT