ledgerwerk

CLI reference

This is the authoritative canonical command reference. It is generated from COMMAND_INVENTORY and the registered Click command tree; run the generator check in CI after command changes.

Global options

Global options may appear before the command path:

Option

Effect

--root PATH

Resolve the project from PATH instead of the current directory.

--json

Emit the stable JSON envelope.

--profile

Include diagnostic operation events in JSON output.

--version

Show the installed version.

--install-completion

Install shell completion.

--show-completion

Print shell completion.

Canonical commands

init

Initialize Documentledger storage for a project.

  • Effect: workspace-write

  • Audience: agent

  • Workspace required: no

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger init

Arguments and options

Parameter

Required

Default

Type

--project-name

no

``

text

--documentledger-dir

no

'.ledger'

text

--hidden-config

no

``

boolean

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger init

status

Show concise Documentledger status.

  • Effect: read

  • Audience: both

  • Workspace required: no

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger status

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger status

info

Show full Documentledger storage and configuration inventory.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger info

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger info

doctor

Run detailed read-only diagnostics.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger doctor

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger doctor

check

Run deterministic CI validation gate.

  • Effect: read

  • Audience: agent

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger check

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger check

next-action

Show the single recommended next command.

  • Effect: read

  • Audience: agent

  • Workspace required: no

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger next-action

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger next-action

scan

Run an incremental source scan.

  • Effect: workspace-write

  • Audience: agent

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger scan

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger scan

coverage

Compute documentation coverage metrics.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger coverage

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger coverage

commands

List all registered commands.

  • Effect: read

  • Audience: both

  • Workspace required: no

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger commands

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger commands

help

Show help for a command path.

  • Effect: read

  • Audience: both

  • Workspace required: no

  • Targeting: command-path

  • Compatibility aliases: None

Syntax

documentledger help

Arguments and options

Parameter

Required

Default

Type

command_path

no

[]

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger help

config show

Show effective Documentledger configuration.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger config show

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger config show

config validate

Validate the effective tool config.

  • Effect: read

  • Audience: agent

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger config validate

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger config validate

schema list

List known schema names.

  • Effect: read

  • Audience: agent

  • Workspace required: no

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger schema list

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger schema list

schema show

Show metadata for a schema.

  • Effect: read

  • Audience: agent

  • Workspace required: no

  • Targeting: schema-name

  • Compatibility aliases: None

Syntax

documentledger schema show

Arguments and options

Parameter

Required

Default

Type

name

yes

``

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger schema show

schema values

Show known values for a schema.

  • Effect: read

  • Audience: agent

  • Workspace required: no

  • Targeting: schema-name

  • Compatibility aliases: None

Syntax

documentledger schema values

Arguments and options

Parameter

Required

Default

Type

name

no

``

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger schema values

document list

List tracked documentation files.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: docs list

Syntax

documentledger document list

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger document list

document sections

Show sections in documentation files.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: document-or-section

  • Compatibility aliases: docs sections

Syntax

documentledger document sections

Arguments and options

Parameter

Required

Default

Type

--doc

no

``

text

--all

no

``

boolean

--ids-only

no

``

boolean

--outline

no

``

boolean

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger document sections

document affected

Show documentation sections affected by source changes.

  • Effect: read

  • Audience: agent

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: docs affected

Syntax

documentledger document affected

Arguments and options

Parameter

Required

Default

Type

--doc

no

``

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger document affected

document stale

Show stale documentation details.

  • Effect: read

  • Audience: agent

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: docs stale

Syntax

documentledger document stale

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger document stale

document build-context

Build a bounded documentation update context.

  • Effect: workspace-write

  • Audience: agent

  • Workspace required: yes

  • Targeting: document-or-section

  • Compatibility aliases: docs build-context

Syntax

documentledger document build-context

Arguments and options

Parameter

Required

Default

Type

--doc

no

``

text

--section

no

``

text

--all

no

``

boolean

--affected

no

``

boolean

--bootstrap

no

``

boolean

--include-unlinked

no

``

boolean

--out

no

``

text

--print

no

``

boolean

--max-source-lines

no

40

integer

--max-section-lines

no

80

integer

--max-bytes

no

250000

integer

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger document build-context

document mark-fresh

Mark documentation sections as fresh.

  • Effect: workspace-write

  • Audience: agent

  • Workspace required: yes

  • Targeting: document-or-section

  • Compatibility aliases: mark-fresh

Syntax

documentledger document mark-fresh

Arguments and options

Parameter

Required

Default

Type

--doc

no

``

text

--section

no

``

text

--all

no

``

boolean

--allow-unlinked

no

``

boolean

--reason

yes

``

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger document mark-fresh

source list

List source units in the inventory.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: sources list

Syntax

documentledger source list

Arguments and options

Parameter

Required

Default

Type

--kind

no

``

text

--path

no

``

text

--path-prefix

no

``

text

--qualname

no

``

text

--query

no

``

text

--ids-only

no

``

boolean

--include-hashes

no

``

boolean

--limit

no

100

integer

--cursor

no

``

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger source list

source show

Show details for a source unit.

  • Effect: read

  • Audience: both

  • Workspace required: yes

  • Targeting: source-unit

  • Compatibility aliases: sources show

Syntax

documentledger source show

Arguments and options

Parameter

Required

Default

Type

source_id

yes

``

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger source show

storage where

Show Documentledger storage locations.

  • Effect: read

  • Audience: both

  • Workspace required: no

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger storage where

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger storage where

storage validate

Validate canonical storage bindings.

  • Effect: read

  • Audience: agent

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: storage verify

Syntax

documentledger storage validate

Arguments and options

Parameter

Required

Default

Type

--strict

no

``

boolean

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger storage validate

migrate status

Show migration status and available migrations.

  • Effect: read

  • Audience: both

  • Workspace required: no

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger migrate status

Arguments and options

  • None.

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger migrate status

migrate plan

Generate a migration plan without applying it.

  • Effect: read

  • Audience: agent

  • Workspace required: yes

  • Targeting: migration-name

  • Compatibility aliases: None

Syntax

documentledger migrate plan

Arguments and options

Parameter

Required

Default

Type

migration_name

no

'storage-layout'

text

--output

no

``

text

--adopt-project-uuid

no

``

boolean

--repair-missing-source-index

no

``

boolean

--retain-unknown

no

``

boolean

--reject-unknown

no

``

boolean

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger migrate plan

migrate apply

Apply a validated migration plan.

  • Effect: workspace-write

  • Audience: agent

  • Workspace required: yes

  • Targeting: migration-name

  • Compatibility aliases: None

Syntax

documentledger migrate apply

Arguments and options

Parameter

Required

Default

Type

migration_name

no

'storage-layout'

text

--plan-file

no

``

text

--dry-run

no

``

boolean

--adopt-project-uuid

no

``

boolean

--repair-missing-source-index

no

``

boolean

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger migrate apply

migrate recover

Recover from an interrupted migration.

  • Effect: workspace-write

  • Audience: agent

  • Workspace required: yes

  • Targeting: none

  • Compatibility aliases: None

Syntax

documentledger migrate recover

Arguments and options

Parameter

Required

Default

Type

--journal

yes

``

text

--policy

no

'auto'

text

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger migrate recover

migrate cleanup

Clean up legacy source after migration.

  • Effect: workspace-write

  • Audience: agent

  • Workspace required: yes

  • Targeting: migration-name

  • Compatibility aliases: None

Syntax

documentledger migrate cleanup

Arguments and options

Parameter

Required

Default

Type

migration_name

no

'storage-layout'

text

--journal

no

``

text

--dry-run

no

``

boolean

--yes

no

``

boolean

--discard-derived

no

``

boolean

--remove-external-source

no

``

boolean

JSON result and errors

With --json, the command returns ok, command, a command-specific result, and events. Failures return the normalized error object with code, message, remediation, and details.domain_code. Invalid workspace, selector, cursor, link, or migration state is reported before a write when applicable.

Example

documentledger migrate cleanup

Compatibility commands

Compatibility interfaces are documented separately and are not canonical inventory entries:

Compatibility path

Use instead

docledger executable

documentledger

docs ...

document ...

sources ...

source ...

links ...

link ...

root mark-fresh

document mark-fresh

storage verify

storage validate

storage migrate

migrate plan or migrate apply

storage recover

migrate recover

storage cleanup-legacy

migrate cleanup

Deprecated since version 0.6: These wrappers remain for compatibility and may emit deprecation warnings. New automation must use canonical command paths.