CLI guide

--json is a global option, so place it before the subcommand: archledger --json read ... rather than archledger read --json.

Ledger boundary

Archledger is an isolated architecture ledger. It stores architecture records, record links, and source references. It does not import/export behavior specs, enforce SDD policy, or coordinate external ledgers.

Use context and trace for architecture retrieval, check for ledger validation, source for change tracking, and mutation commands under record, refs, links, and ac. JSON Schemas are returned with schema --format jsonschema --target TARGET. install creates optional integration scaffolds and refuses overwrites unless --force is supplied.

The canonical record and migration syntax is:

archledger --json storage where
archledger --json record create adr "Architecture decision"
archledger --json record list
archledger --json record show adr-0001
archledger --json record read --body
archledger --json record archive adr-0001 --reason "superseded"
archledger --json migrate plan identity-ledgercore
archledger --json migrate apply identity-ledgercore --reason "approved migration"

Compatibility aliases remain available with structured deprecation warnings. The complete inventory is in the generated CLI reference.

`init` — Initialize a workspace

Creates .ledger/ledger.toml, .ledger/archledger/config.toml, canonical repository data, section stubs, record-type subdirectories, and storage.yaml in one step.

Legacy layouts fail with migration instructions. A valid canonical project is idempotent.

Synopsis

archledger init [OPTIONS]

Quick start

# Markdown project
archledger init --source-format markdown

# AsciiDoc project (default when --source-format is omitted)
archledger init --source-format asciidoc

What init creates

Running init produces:

.ledger/ledger.toml - shared project identity and ledger topology
.ledger/archledger/config.toml - stable Archledger settings
.ledger/archledger/data/ - authoritative repository data
.ledger/archledger/data/profiles/arc42/sections/ - section stubs
.ledger/archledger/data/records/ - typed record directories
.ledger/archledger/data/archive/ - archived records
.ledger/archledger/data/storage.yaml - ledger counter state

Section files are numbered by configured [ids] format (default al_0001 through al_0012) matching the 12 major arc42 sections:

Introduction and Goals
Architecture Constraints
Context and Scope
Solution Strategy
Building Block View
Runtime View
Deployment View
Cross-cutting Concepts
Architecture Decisions
Quality Requirements
Risks and Technical Debt
Glossary

After init, add starter content with:

archledger seed arc42-minimal

Core options

--source-format FORMAT Canonical source dialect: markdown or asciidoc. Default: asciidoc. Determines file extensions, default build output name, and template rendering for all generated section stubs.

--archledger-dir PATH Deprecated and rejected. Canonical storage is fixed at .ledger/archledger/data; use archledger migrate project for legacy paths.

--project-name TEXT Stable project identity stored in .ledger/ledger.toml. Defaults to the workspace directory basename (slug-normalized).

--project-uuid TEXT Stable project UUID. Auto-generated when omitted. Must be a valid UUID format.

--id-prefix TEXT Ledger ID prefix for generated section/record IDs (for example al or ta). Default: al.

--id-width N Minimum digit width for generated ledger IDs. Default: 4.

--id-segment-mode MODE Ledger ID segment mode: none or type. Default: none.

Build options

--build-default-format FORMAT Default build output format: markdown, asciidoc, pdf, or docx. When omitted, defaults to the source format.

--build-default-output FILENAME Default build output filename. When omitted, defaults to architecture.<ext> matching the source format.

--build-default-output-dir DIR Build output directory, relative to the config path. Default: build.

--build-include-draft Include draft records in build output.

--build-include-superseded Include superseded records in build output.

--build-strict Enable strict build mode.

--build-keep-intermediate Keep intermediate build files.

--build-converter TOOL Build converter tool: auto, pandoc, or asciidoctor. Default: auto.

--build-pdf-engine ENGINE PDF engine for pandoc builds.

--build-reference-docx PATH Reference docx template for pandoc builds.

Diagram options

--diagrams / --no-diagrams Enable diagram support. Default: --no-diagrams.

--diagram-renderer RENDERER Diagram renderer: pass-through, mermaid-cli, or asciidoctor-diagram. Default: pass-through.

--diagram-default-type TYPE Default diagram type: text, ascii, unicode, svgbob, or mermaid. Default: text.

--diagram-output-dir DIR Diagram output directory. Default: diagrams.

--diagram-image-format FORMAT Diagram image format: svg or png. Default: svg.

--diagram-kroki-url URL Kroki server URL (reserved for future renderers).

arc42 options

--arc42-title TEXT arc42 template title. Default: Architecture Documentation.

--arc42-language CODE arc42 template language. Default: en.

--arc42-template-version VERSION arc42 template version. Default: 9.0-EN.

--arc42-include-help / --no-arc42-include-help Include arc42 help sections in generated section stubs. Default: --no-arc42-include-help.

Tracking options

--tracking / --no-tracking Enable source tracking. Default: --tracking.

--tracking-scanner SCANNER Tracking scanner: auto, git, or filesystem. Default: auto.

--tracking-state-file FILENAME Tracking state filename. Default: source-state.json.

--tracking-max-file-bytes N Maximum file size in bytes for tracking. Default: 1000000.

--tracking-include GLOB Glob pattern for tracking includes. Repeatable.

--tracking-exclude GLOB Glob pattern for tracking excludes. Repeatable.

Examples

Minimal Markdown project with build output at the project root:

archledger init --source-format markdown \
  --build-default-output ARCHITECTURE.md \
  --build-default-output-dir .

AsciiDoc project with diagram support, German arc42 template, and custom tracking excludes:

archledger init --source-format asciidoc \
  --diagrams \
  --diagram-default-type mermaid \
  --arc42-title "Meine Systemarchitektur" \
  --arc42-language de \
  --tracking-exclude "vendor/**" \
  --tracking-exclude "**/__pycache__/**"

External state directory:

archledger init --archledger-dir /shared/archledger-state

Segmented IDs for record-type-based naming:

archledger init --source-format markdown --id-segment-mode type

JSON output for automation:

archledger --json init --source-format markdown

Other commands

Inspect the current source state:

archledger --json paths
archledger --json status
archledger --json check
archledger --json doctor
archledger --json read --body --include-drafts

When check reports legacy IDs or legacy timestamp metadata, inspect the migration dry runs first:

archledger --json migrate ids --to ledgercore
archledger --json migrate metadata --to versioned

Track implementation drift:

archledger --json source changed
archledger --json source changed --fail-on-unlinked
archledger --json source snapshot --reason after-archledger-update

Create records:

archledger --json new requirement "Render architecture document" --status proposed
archledger --json new adr "Treat source fragments as canonical" --status proposed
archledger --json new diagram "Runtime login flow" --section runtime_view --status proposed

Capture the returned result.id from new; do not predict record IDs.

Typed metadata mutation:

archledger record meta set runtime-0013 participants --json-value '["caller", "service"]'
archledger record meta set content-0013 source --string-value "--json envelopes are supported"
archledger record meta set runtime-0013 participants --from-file participants.yaml
archledger record body set runtime-0013 --from-file /tmp/runtime-body.md

Archive and repair:

archledger archive content-0022 --reason "obsolete after content-0041"
archledger doctor
archledger doctor --repair

Renumber IDs and references:

archledger renumber --prefix ta --width 3
archledger renumber --prefix ta --width 3 --apply
archledger renumber --id-segment-mode type
archledger renumber --id-segment-mode type --apply
archledger renumber --id-segment-mode none --apply

check is read-only. It validates numbering and integrity but does not mutate counters or source files. Use archledger --json check --strict before finalizing agent-driven updates.

Build output:

archledger build --format markdown
archledger build --format asciidoc
archledger build --format html --format markdown

Project storage migration

See Storage and migration for derived paths, topology changes, strict plans, receipts, and the no-manual-move workflow.

Inspect legacy layout without writes:

archledger --json migrate project

Apply with mandatory backup, staging, verification, and a preserved source:

archledger migrate project --apply

Use --backup-dir PATH to select a backup location or --retire-source to timestamp-rename the verified legacy source.