Command-line interface
Ledgence builds one public executable, ledgence, from the ledgence-cli
crate. It packages programs, runs workers and the orchestrator, administers
tasks and approvals, connects MCP clients, and manages a local container stack.
Worker and orchestrator processes run separately and can run on different hosts.
Version availability: Ledgence 0.5.0 includes explicit program builds, HTTP publication and recovery alongside the existing local lifecycle and installed-resource discovery. Start with the one-line installation and local distribution guide.
This replaces the command layout in the historical v0.1.1 source tag and
native 0.1.0 bundle. Those artifacts retain their original executables and
commands; use their bundled documentation when operating them.
Build and inspect
Section titled “Build and inspect”cargo build -p ledgence-cli --locked./target/debug/ledgence --help./target/debug/ledgence --version./target/debug/ledgence program --help./target/debug/ledgence worker --help./target/debug/ledgence orchestrator --help./target/debug/ledgence task --help./target/debug/ledgence approval --help./target/debug/ledgence mcp --help./target/debug/ledgence local --helpUse cargo run --locked -p ledgence-cli -- COMMAND ... to run directly from the
checkout. ledgence --version reports the compiled platform version; an exact
program version passed to ledgence program register --version VALUE continues
to identify the application package.
The default features are otel and mcp. otel enables optional telemetry for
administration, worker and orchestrator commands. The MCP command does not
install a telemetry exporter.
cargo build -p ledgence-cli --no-default-features --locked omits optional integrations.
Use --features sqs to include optional SQS delivery for both worker and
orchestrator commands, or --all-features to include every supported integration.
These are build features; telemetry export and SQS operation still require
explicit runtime configuration. See observability and
dispatch delivery.
Command groups
Section titled “Command groups”Use ledgence <group> <command> --help for the flags accepted by your executable.
MCP requires its build feature, which is included in native release bundles.
| Group | Commands | Purpose |
|---|---|---|
local |
up, status, logs, down |
Manage a saved installation from a pinned Compose distribution. |
program |
example, build, publish, register |
Prepare, publish and register programs; build requires local Docker and an explicit worker target. |
worker |
run, connect |
Execute local fixtures or acquire durable work from an API. |
orchestrator |
migrate, serve, retain |
Apply schema changes, run the API, and preview or apply scoped retention. |
task |
submit, list, inspect, status, result, attempt, history, cancel |
Submit and inspect task executions. |
approval |
list, inspect, decide |
Review and decide persisted workflow actions. |
mcp |
serve |
Expose a scoped Ledgence API through MCP over stdio. |
There is no separate workflow command group. Use the
HTTP API, Python client,
Console or MCP for workflow and event operations.
Local lifecycle
Section titled “Local lifecycle”These commands require Docker running Linux containers and Compose 2.23.1+. The native installation supplies its matching qualified kit:
ledgence local upledgence local statusledgence local logs --follow --service workerledgence local downA source-built CLI needs --distribution /absolute/path/to/qualified-local-kit.
Use --directory /absolute/path/to/state for a separate installation and repeat
it for every command on that installation. Default state lives at $XDG_DATA_HOME/ledgence/local, or
$HOME/.local/share/ledgence/local if unset. The default port is 8080 and
concurrency is 1. Choose a nondefault port, concurrency (1–1024), or named local
Docker --context on first startup; saved options do not change implicitly.
| Command | Behavior |
|---|---|
local up |
Verify and copy the kit on first use, start the saved Compose project, and wait for readiness. Print API/Console URLs, scope, image, context and worker platform. |
local status |
Display all service states and saved settings without starting containers. |
local logs |
Show 100 recent lines per service by default. Accept --tail 1..10000, --follow, and --service postgres|migrate|orchestrator|worker. |
local down |
Stop the project with a 65-second grace period, preserving data volumes and configuration. |
The base stack runs PostgreSQL, a migrator, an orchestrator serving Console,
and one worker in tenant acme, namespace demo, queue demo. Programs and
the callback receiver are optional additions. The CLI rejects remote Docker
endpoints and checks the kit’s qualified platforms against the engine.
The saved state remains tied to its original absolute directory and Docker
endpoint. Installing a newer CLI does not upgrade that stack. There is no
local restore command; database and program-store backups are separate from
the state directory. See local distribution operations
for startup failures, data preservation and direct Compose use.
Installed resources
Section titled “Installed resources”The CLI resolves symlink launchers and locates resources relative to the actual executable in a complete bundle:
worker runandworker connectuse the bundledruntime/ledgence/worker/bootstrap.pywhen--runneris omitted and the file exists. An explicit--runnerwins; source builds without the bundle layout still require it.orchestrator serve --instance-config FILEuses bundledconsole/assets when they exist and--console-diris omitted. An explicit--console-dirwins and still requires instance configuration.- Without
--instance-config, the orchestrator remains headless. Finding Console files does not enable Console on its own.
Keep the complete bundle, including legal notices, together when moving a
native installation. The host CPython interpreter is supplied separately.
The native installation guide also explains explicit
--runner and --console-dir overrides for operator-managed service configurations.
Command migration
Section titled “Command migration”Update executable names and command prefixes in shell scripts, process managers, and deployment configuration:
| Previous command | Current command |
|---|---|
ledgence-worker example |
ledgence program example |
ledgence-worker publish |
ledgence program publish |
ledgence-worker run |
ledgence worker run |
ledgence-worker connect |
ledgence worker connect |
ledgence-orchestrator migrate |
ledgence orchestrator migrate |
ledgence-orchestrator serve |
ledgence orchestrator serve |
ledgence-orchestrator retain |
ledgence orchestrator retain |
ledgence task ... |
ledgence task ... |
ledgence program register ... |
ledgence program register ... |
Keep each command’s existing options after its new prefix. The 0.5.0 source builds
and native bundles contain only the ledgence executable; they do not
provide legacy executable aliases. The ledgence-worker and
ledgence-orchestrator Rust crates remain internal composition libraries.
Telemetry service names remain ledgence-worker, ledgence-orchestrator, and
ledgence-cli for the corresponding roles.
program example creates a local fixture and program publish writes immutable
package contents to a store. program register makes a separate HTTP request to
register an existing published reference. Publication starts no worker or
execution. Ledgence 0.5.0 supports explicit subsequent registration
with publish --server URL --register. See program packages and
Console registration.
worker run executes local task fixtures; worker connect acquires work from a
service. orchestrator migrate applies database migrations explicitly;
orchestrator serve verifies the schema and starts the service. Retention stays
an explicit scoped operator operation through orchestrator retain.
Both migration and service operation require DATABASE_URL. Retention previews
eligible records by default, requires a tenant and namespace, and changes data
only with --apply; its minimum retention is 90 days. See
retention.
Program builds and HTTP publication
Section titled “Program builds and HTTP publication”Use matching 0.5.0 CLI and server components. A server must opt in with
--allow-program-publication, an --instance-config and writable filesystem
--store; an existing released stack does not gain this by updating its CLI.
ledgence program build --config ledgence.toml --output .ledgence/preparedledgence program publish --source .ledgence/prepared \ --server http://127.0.0.1:8080 --registerledgence program publish --resume /absolute/path/to/receipt.jsonbuild accepts --config (default ledgence.toml), --output (default
.ledgence/prepared, relative to the config directory), --context NAME and
--timeout-seconds 1..3600 (default 600). The configuration declares selected
inputs, exact target, hash-pinned production wheels and the worker runtime image
by digest. It uses local Docker and refuses to overwrite an existing output.
publish requires exactly one destination: --store DIR or --server URL.
--source defaults to .ledgence/prepared. It never builds implicitly. For
HTTP, --register uses matching build-receipt metadata unless --kind,
--display-name or --description overrides it. --update-metadata true
explicitly replaces existing descriptive values. --store retains descriptor-only
JSON and rejects registration options.
--resume RECEIPT.json cannot be combined with other options. It verifies the
retained ZIP and repeats only unconfirmed stages at the recorded server. A
registration failure after a confirmed upload returns nonzero and partial JSON,
including the published descriptor and a registration-only command. Separate
registration can require --expected-digest sha256:HEX --expected-size BYTES
together. See Build and publish Python programs
for configuration, complete output and recovery semantics.
Task administration
Section titled “Task administration”The task commands, approval commands and program register use one
bounded exchange, one JSON result on stdout, and diagnostics on stderr. Exit
status 0 means the operation was accepted, 2 means an input or usage
rejection, and 1 means a service or transport failure. A successful submission
does not mean the task completed successfully. After an uncertain submission,
retry the same input and idempotency key to reconcile the original request.
Use task list to discover work, task status for scheduling metadata,
task result for the authoritative logical outcome, and task inspect,
task attempt, and task history for diagnostics. task cancel requests
cancellation. See the HTTP quickstart for
complete examples and the task result contract for outcome
semantics.
ledgence task submit --server http://127.0.0.1:8080 --file task.jsonledgence task list --server http://127.0.0.1:8080 --tenant acme --namespace demoledgence task result --server http://127.0.0.1:8080 \ --tenant acme --namespace demo --task TASK_IDtask.json contains the complete submission command, including its
idempotency_key. task list accepts state, queue, correlation and submission
time filters; pass its returned cursor with unchanged filters for another page.
task result reads the current result once and does not wait for completion.
task history --after N starts after a recorded sequence, and task attempt
requires both task and attempt IDs.
Approval decisions
Section titled “Approval decisions”Use approval list and inspect to review persisted requests and their exact
effective actions:
ledgence approval list --server http://127.0.0.1:8080 \ --tenant acme --namespace demo --workflow WORKFLOW_ID --limit 10ledgence approval inspect --server http://127.0.0.1:8080 \ --tenant acme --namespace demo --workflow WORKFLOW_ID --key APPROVAL_KEYledgence approval decide --server http://127.0.0.1:8080 --file decision.jsonPass the list response’s next_cursor as --after-key for the next page.
The saved decision includes scope, workflow_id, key, activation_id,
revision, action, decision_id, decision, reviewer, and reason.
After an uncertain response, retry the identical file to reconcile that
decision. Generic events cannot approve actions. See
durable approvals
for the complete contract and examples.
Ledgence 0.5.0 builds enable the optional mcp feature by default.
ledgence mcp serve --server URL --tenant ID --namespace NAME connects an MCP
client over stdio to that API. Add --read-only for observation only.
Scope is fixed for the session. Submissions require caller-supplied idempotency
keys and return immediately; inspect results separately. Stdout carries MCP
messages. The process starts no database, worker or model provider.
See Connect an MCP client.
--no-default-features --features mcp builds MCP without OpenTelemetry or SQS.
Earlier 0.2.0 binaries do not include this command.