### Run Quickstart Example

Source: https://github.com/yaogdu/agentledger/blob/main/go/examples/README.md

Runs the quickstart example from the repository root. The source file is quickstart/main.go.

```bash
go run ./go/examples/quickstart
```

--------------------------------

### Run Quickstart Example

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/examples/README.md

Run the quickstart example from the typescript/ directory. The source file is quickstart/quickstart.js.

```bash
cd typescript
node examples/quickstart/quickstart.js
```

--------------------------------

### Run Rust quickstart from repository

Source: https://github.com/yaogdu/agentledger/blob/main/docs/GETTING_STARTED.md

From the rust directory, run the quickstart CLI and example.

```bash
cd rust
cargo run --quiet -- quickstart
cargo run --quiet --example quickstart
```

--------------------------------

### Run TypeScript quickstart from repository

Source: https://github.com/yaogdu/agentledger/blob/main/docs/GETTING_STARTED.md

From the repository root, run the TypeScript CLI and the quickstart example.

```bash
cd typescript
node src/cli.js quickstart
node examples/quickstart/quickstart.js
```

--------------------------------

### Run CLI Quickstart and Conformance

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/examples/README.md

Run the CLI quickstart and conformance commands from the typescript/ directory. The package surface is agentledger-runtime; see ../README.md for package metadata and API examples.

```bash
cd typescript
node src/cli.js quickstart
node src/cli.js conformance
```

--------------------------------

### Install and use agentledger-go CLI

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Installs the optional CLI command and runs its help, doctor, and quickstart subcommands. Note that installing the library package directly fails because it is not a package main; use /cmd/agentledger-go.

```bash
go install github.com/yaogdu/AgentLedger/go/cmd/agentledger-go@v1.5.4
agentledger-go --help
agentledger-go doctor
agentledger-go quickstart
```

--------------------------------

### Install AgentLedger Python via pipx and run CLI

Source: https://github.com/yaogdu/agentledger/blob/main/docs/GETTING_STARTED.md

Install the Python runtime with pipx, then verify the CLI and generate a quickstart project.

```bash
pipx install agentledger-runtime
agentledger --help
agentledger quickstart
```

--------------------------------

### Run Hello World Example

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USAGE.md

Run the included hello world example.

```bash
PYTHONPATH=src python3 examples/hello_world/hello.py
```

--------------------------------

### Editable install and verify CLI

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USAGE.md

Performs an editable install after packaging setup and verifies the CLI with --help.

```bash
python3 -m pip install -e .
agentledger --help
```

--------------------------------

### Run Rust package verification

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Commands to run tests, conformance, and the quickstart example in the local Rust repository.

```bash
cd rust
cargo test --lib --bins
cargo run --quiet -- conformance
cargo run --quiet --example quickstart
```

--------------------------------

### Run dependency-free example smoke tests

Source: https://github.com/yaogdu/agentledger/blob/main/docs/RELEASE_CHECKLIST.md

Run representative dependency-free examples to verify basic functionality. Each command sets PYTHONDONTWRITEBYTECODE=1 and PYTHONPATH=src, then executes a specific example script or module.

```bash
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 examples/hello_world/hello.py
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 examples/langgraph/basic_graph.py
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 examples/inspector/custom_viewer.py
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 examples/media_stream/basic_media_stream.py
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 examples/media_stream/managed_tool.py
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger worker-run examples/transient_retry
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger tools manifest --format agentledger --example examples/docs
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 -m agentledger tools manifest --format agentledger --example examples/media_stream
```

--------------------------------

### Run media stream examples and generate manifest

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USAGE.md

Run the media stream examples and generate a manifest for the media_stream example directory. The runtime core stores refs, metadata, lineage, offsets, and checkpoints but does not decode media or implement stream transport.

```bash
PYTHONPATH=src python3 examples/media_stream/basic_media_stream.py
PYTHONPATH=src python3 examples/media_stream/managed_tool.py
PYTHONPATH=src python3 -m agentledger tools manifest --format agentledger --example examples/media_stream
```

--------------------------------

### Run CLI quickstart and conformance

Source: https://github.com/yaogdu/agentledger/blob/main/rust/examples/README.md

Runs the CLI quickstart and conformance commands. The crate surface is agentledger-runtime, and the library crate is imported as agentledger.

```bash
cd rust
cargo run --quiet -- quickstart
cargo run --quiet -- conformance
```

--------------------------------

### Adapter package build, install, and import checks

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_PACKAGING.md

Commands each adapter package should also pass: build the package, install the wheel, and verify the import works.

```bash
python3 -m build packages/<adapter>
python3 -m pip install dist/<adapter>.whl
python3 -c "import <adapter_import_name>"
```

--------------------------------

### Adapter quickstart with Postgres and S3

Source: https://github.com/yaogdu/agentledger/blob/main/rust/README.md

Shows how to use the optional Postgres and S3 adapters. Requires injected clients and applies migrations for Postgres.

```rust
use agentledger::{PostgresAdapter, S3BlobStoreAdapter};

let mut pg = PostgresAdapter::new(injected_sql_client, "agentledger");
pg.apply_migrations()?;

let mut s3 = S3BlobStoreAdapter::new(injected_object_client, "agentledger-test", "agentledger/blobs");
let (_digest, reference) = s3.put_json(&value)?;
println!("{}", reference);
```

--------------------------------

### Run custom viewer example

Source: https://github.com/yaogdu/agentledger/blob/main/examples/inspector/README.md

Run the custom viewer example from the repository root. It creates a temporary local runtime, runs one tool-using agent, and writes a JSON report and a static HTML report under a temporary directory, printing their paths.

```bash
PYTHONPATH=src python3 examples/inspector/custom_viewer.py
```

--------------------------------

### Install AgentLedger Go CLI

Source: https://github.com/yaogdu/agentledger/blob/main/docs/GETTING_STARTED.md

Install the optional Go CLI and verify it with --help.

```bash
go install github.com/yaogdu/AgentLedger/go/cmd/agentledger-go@v1.5.4
agentledger-go --help
```

--------------------------------

### Run the OpenAI Agents SDK-style approval and replay example

Source: https://github.com/yaogdu/agentledger/blob/main/examples/openai_agents/README.md

Run the example from the repository root. The script simulates an OpenAI Agents SDK-style runner that records model evidence, proposed tool calls, approval, Tool Ledger, evidence export, and replay without importing the real SDK or calling the network.

```bash
PYTHONPATH=src python3 examples/openai_agents/approval_replay.py
```

--------------------------------

### AgentLedger Go adapter quickstart

Source: https://github.com/yaogdu/agentledger/blob/main/go/README.md

Demonstrates the optional adapter APIs: Postgres migrations, S3 blob storage, and Docker sandbox configuration. Requires injected SQL and object clients; the sandbox executor is set on the runtime and the manifest is printed.

```go
pg := agentledger.NewPostgresAdapter("agentledger", injectedSQLClient)
_ = pg.ApplyMigrations(context.Background())

s3 := agentledger.NewS3BlobStore("agentledger-test", "agentledger/blobs", injectedObjectClient)
_, ref, _ := s3.PutJSON(context.Background(), agentledger.JSONObject{"answer": "ok"})
fmt.Println(ref)

manifest := (agentledger.DockerSandboxAdapter{}).Manifest(
    agentledger.SandboxPolicy{Network: "deny"},
    []string{"echo", "ok"},
)

rt.SetSandbox(agentledger.DockerSandboxExecutor{
    Image: "python:3.11-slim",
    AllowCommandExecution: true,
})
fmt.Println(manifest)
```

--------------------------------

### Install dependencies and run local adapter validation

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_CERTIFICATION.md

Install the required Python packages and run the local adapter validation script. The script starts disposable Docker services and runs Postgres StateStore conformance, Postgres worker concurrency conformance, and MinIO-backed S3 BlobStore conformance. The generated adapter-validation.json uses schema agentledger.adapter_validation.v1 and can be attached to release or adapter certification notes.

```bash
python3 -m pip install "psycopg[binary]" boto3
```

```bash
bash scripts/validate_adapters_local.sh --output-dir /tmp/agentledger-adapter-validation
```

--------------------------------

### Install by feature through extras: pip install agentledger-runtime[...]

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_PACKAGING.md

Installs the core runtime with optional adapter extras for postgres, mysql, s3, langgraph, mcp, otel, langfuse, docker, inspector, or all.

```bash
pip install "agentledger-runtime[postgres]"
pip install "agentledger-runtime[mysql]"
pip install "agentledger-runtime[s3]"
pip install "agentledger-runtime[langgraph]"
pip install "agentledger-runtime[mcp]"
pip install "agentledger-runtime[otel]"
pip install "agentledger-runtime[langfuse]"
pip install "agentledger-runtime[docker]"
pip install "agentledger-runtime[inspector]"
pip install "agentledger-runtime[all]"
```

--------------------------------

### Install agentledger-sandbox-docker

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-sandbox-docker/README.md

Install the runtime and the Docker sandbox adapter package.

```bash
npm install agentledger-runtime agentledger-sandbox-docker
```

--------------------------------

### Minimal AgentLedger Go runtime example

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Minimal runtime example: creates a local runtime, registers a tool, runs a single step, and exports evidence. Uses NewLocalRuntime, RegisterTool, CreateRun, RunOnce, and ExportEvidence.

```go
package main

import (
    "context"
    "fmt"

    agentledger "github.com/yaogdu/AgentLedger/go"
)

func main() {
    rt, err := agentledger.NewLocalRuntime(".agentledger-go/state.json")
    if err != nil { panic(err) }

    _ = rt.RegisterTool(agentledger.ToolSpec{
        Name: "docs.echo",
        Func: func(ctx context.Context, args agentledger.JSONObject) (any, error) {
            return agentledger.JSONObject{"echo": args["text"]}, nil
        },
    })

    runID, _, _ := rt.CreateRun(agentledger.JSONObject{"input": "hello"})
    _, err = rt.RunOnce(context.Background(), runID, "worker-go", "Agent", 60,
        func(ctx context.Context, agentCtx *agentledger.AgentContext, state agentledger.JSONObject) error {
            result, err := agentCtx.CallTool(ctx, "docs.echo", agentledger.JSONObject{"text": state["input"]})
            if err != nil { return err }
            return agentCtx.WriteState("result", result)
        },
    )
    if err != nil { panic(err) }
    evidence, _ := agentledger.ExportEvidence(rt.Store, runID)
    fmt.Println(evidence.Run.RunID)
}
```

--------------------------------

### Install agentledger-otel

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-otel/README.md

Install the agentledger-runtime and agentledger-otel packages from npm.

```bash
npm install agentledger-runtime agentledger-otel
```

--------------------------------

### Install for local development with editable install

Source: https://github.com/yaogdu/agentledger/blob/main/README.md

Installs the package in editable mode for local development and runs the doctor command to verify the setup. Requires Python 3.11 or newer; if the system python3 is older, replace python3 with python3.11.

```bash
python3 -m pip install -e .
agentledger doctor
```

--------------------------------

### Install optional client dependencies

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_VALIDATION.md

Installs the optional client dependencies required to run the local adapter validation script.

```bash
python3 -m pip install "psycopg[binary]" boto3
```

--------------------------------

### Install agentledger-otel and runtime adapter

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-otel/README.md

Install the agentledger-otel package and the optional OpenTelemetry adapter for agentledger-runtime.

```bash
pip install agentledger-otel
pip install "agentledger-runtime[otel]"
```

--------------------------------

### Install agentledger-s3 and agentledger-runtime with S3 extra

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-s3/README.md

Install the package with pip. The second command installs the runtime with the optional S3 extra.

```bash
pip install agentledger-s3
pip install "agentledger-runtime[s3]"
```

--------------------------------

### Install Python runtime and run doctor

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Installs the Python runtime from PyPI and runs the doctor command to verify the installation.

```bash
python3 -m pip install agentledger-runtime
agentledger doctor
```

--------------------------------

### Install agentledger-mysql

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-mysql/README.md

Install the MySQL adapter package and the runtime with MySQL extras.

```bash
pip install agentledger-mysql
pip install "agentledger-runtime[mysql]"
```

--------------------------------

### Install agentledger-postgres and runtime

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-postgres/README.md

Installs the agentledger-runtime and agentledger-postgres packages from npm.

```bash
npm install agentledger-runtime agentledger-postgres
```

--------------------------------

### Install agentledger-postgres

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-postgres/README.md

Install the Postgres adapter package or the runtime with Postgres extras.

```bash
pip install agentledger-postgres
pip install "agentledger-runtime[postgres]"
```

--------------------------------

### Install agentledger-s3

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-s3/README.md

Install the agentledger-runtime and agentledger-s3 packages from npm.

```bash
npm install agentledger-runtime agentledger-s3
```

--------------------------------

### Install and use MySQLAdapter

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-mysql/README.md

Install the MySQL adapter and runtime packages, then create a MySQLAdapter instance with your MySQL client and apply migrations. The package re-exports agentledger-runtime/mysql and requires you to inject the client used by your application.

```bash
npm install agentledger-mysql agentledger-runtime
```

```js
import { MySQLAdapter } from 'agentledger-mysql';

const adapter = new MySQLAdapter(mysqlClient);
await adapter.applyMigrations();
```

--------------------------------

### AgentLedger Go runtime quickstart

Source: https://github.com/yaogdu/agentledger/blob/main/go/README.md

Shows the core AgentLedger Go runtime loop: create a local runtime, register a tool, create a run, execute it once with a worker, and export evidence. The tool receives a JSON object and returns a JSON object; the agent writes the result to state.

```go
package main

import (
    "context"
    "fmt"

    agentledger "github.com/yaogdu/AgentLedger/go"
)

func main() {
    rt, err := agentledger.NewLocalRuntime(".agentledger-go/state.json")
    if err != nil { panic(err) }

    _ = rt.RegisterTool(agentledger.ToolSpec{
        Name: "docs.echo",
        Func: func(ctx context.Context, args agentledger.JSONObject) (any, error) {
            return agentledger.JSONObject{"echo": args["text"]}, nil
        },
    })

    runID, _, _ := rt.CreateRun(agentledger.JSONObject{"input": "hello"})
    _, err = rt.RunOnce(context.Background(), runID, "worker-go", "Agent", 60,
        func(ctx context.Context, agentCtx *agentledger.AgentContext, state agentledger.JSONObject) error {
            result, err := agentCtx.CallTool(ctx, "docs.echo", agentledger.JSONObject{"text": state["input"]})
            if err != nil { return err }
            return agentCtx.WriteState("result", result)
        },
    )
    if err != nil { panic(err) }

    bundle, _ := agentledger.ExportEvidence(rt.Store, runID)
    fmt.Println(bundle.Run.RunID)
}
```

--------------------------------

### First 10 Minutes: Verify Runtime with agentledger CLI

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USAGE.md

Quick-start commands to verify the runtime locally. The sequence runs the hello world example, then uses the agentledger CLI to run, debug, inspect the ledger, replay, export evidence, and generate an inspector report for a run.

```bash
PYTHONPATH=src python3 examples/hello_world/hello.py
PYTHONPATH=src python3 -m agentledger --root .agentledger-demo run examples/side_effect_idempotency
PYTHONPATH=src python3 -m agentledger --root .agentledger-demo debug <run_id> --json --include-diffs
PYTHONPATH=src python3 -m agentledger --root .agentledger-demo ledger <run_id>
PYTHONPATH=src python3 -m agentledger --root .agentledger-demo replay <run_id>
PYTHONPATH=src python3 -m agentledger --root .agentledger-demo evidence <run_id> --html ./evidence.html
PYTHONPATH=src python3 -m agentledger --root .agentledger-demo inspector run <run_id> --html ./inspector.html
```

--------------------------------

### Generate Adapter Certification Bundle

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_CERTIFICATION.md

Commands to generate a machine-readable starting certification bundle for official adapter profiles. Use the --out flag to specify the output file and --package-name for adapters with a custom package name.

```bash
PYTHONPATH=src python3 -m agentledger adapter certify --kind postgres --adapter-version 1.4.0
PYTHONPATH=src python3 -m agentledger adapter certify --kind mysql --adapter-version 1.4.0 --out ./mysql-certification.json
PYTHONPATH=src python3 -m agentledger adapter certify --kind s3 --adapter-version 1.4.0 --out ./s3-certification.json
PYTHONPATH=src python3 -m agentledger adapter certify --kind langgraph --adapter-version 1.4.0 --package-name agentledger-langgraph
```

--------------------------------

### Install agentledger-langgraph

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-langgraph/README.md

Install the agentledger-runtime and agentledger-langgraph packages from npm.

```bash
npm install agentledger-runtime agentledger-langgraph
```

--------------------------------

### Run model evidence demo

Source: https://github.com/yaogdu/agentledger/blob/main/examples/model_evidence/README.md

Run the model evidence example from the repository root. The output includes Inspector read-model counts for `model_calls` and `tool_proposals`.

```bash
PYTHONPATH=src python3 examples/model_evidence/demo.py
```

--------------------------------

### Install MySQL adapter

Source: https://github.com/yaogdu/agentledger/blob/main/docs/MYSQL.md

Install the MySQL adapter as an optional dependency. Use either the extra on the runtime package or the standalone agentledger-mysql package.

```bash
pip install "agentledger-runtime[mysql]"
# or
pip install agentledger-mysql
```

--------------------------------

### Compatibility target file paths

Source: https://github.com/yaogdu/agentledger/blob/main/go/README.md

Lists the compatibility target files: runtime contract, conformance semantics, language quickstart, and parity matrix. These are relative paths from the go directory.

```text
../contracts/agentledger.runtime.v1.json
../contracts/conformance/runtime_semantics.v1.json
../docs/LANGUAGE_QUICKSTART.md
../docs/LANGUAGE_PARITY_MATRIX.md
```

--------------------------------

### Install and use agentledger-inspector

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_PACKAGING.md

Install the inspector package and run it to generate HTML evidence and run reports.

```bash
pip install "agentledger-runtime[inspector]"
agentledger inspector evidence ./evidence/<run_id> --html ./inspector.html
agentledger inspector run <run_id> --root .agentledger --html ./inspector.html
```

--------------------------------

### Install agentledger-runtime from PyPI and verify

Source: https://github.com/yaogdu/agentledger/blob/main/README.md

Installs the agentledger-runtime package from PyPI and verifies the installation with the CLI help and doctor commands. The PyPI distribution is named agentledger-runtime, but the Python import package and CLI remain agentledger.

```bash
python3 -m pip install agentledger-runtime
agentledger --help
agentledger doctor
```

--------------------------------

### Install agentledger-langfuse

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-langfuse/README.md

Install the agentledger-runtime and agentledger-langfuse packages via npm.

```bash
npm install agentledger-runtime agentledger-langfuse
```

--------------------------------

### Install agentledger-langfuse

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-langfuse/README.md

Install the agentledger-langfuse adapter package and the optional Langfuse runtime extra.

```bash
pip install agentledger-langfuse
pip install "agentledger-runtime[langfuse]"
```

--------------------------------

### Install and import agentledger-mcp-adapter

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/packages/agentledger-mcp/README.md

Install the adapter package and import its main classes. The import statement shows the two primary exports: MCPToolAdapter and MCPContextAdapter.

```bash
npm install agentledger-runtime agentledger-mcp-adapter
```

```js
import { MCPToolAdapter, MCPContextAdapter } from 'agentledger-mcp-adapter';
```

--------------------------------

### Run framework adapter smoke tests

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_CERTIFICATION.md

Recommended smoke tests for framework adapters. These commands run conformance checks for specific adapter kinds and execute example scripts for various frameworks, followed by a lint boundary check.

```bash
PYTHONPATH=src python3 -m agentledger adapter conformance --kind python-function
PYTHONPATH=src python3 -m agentledger adapter conformance --kind langchain
PYTHONPATH=src python3 examples/autogen/basic_agent.py
PYTHONPATH=src python3 examples/crewai/basic_crew.py
PYTHONPATH=src python3 examples/langchain/basic_runnable.py
PYTHONPATH=src python3 examples/langgraph/basic_graph.py
PYTHONPATH=src python3 examples/openai_agents/basic_agent.py
PYTHONPATH=src python3 -m agentledger lint boundary examples
```

--------------------------------

### Install agentledger-mcp and runtime with MCP extras

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-mcp/README.md

Install the agentledger-mcp package and the agentledger-runtime with the MCP extra using pip.

```bash
pip install agentledger-mcp
pip install "agentledger-runtime[mcp]"
```

--------------------------------

### Install agentledger-inspector and generate HTML evidence

Source: https://github.com/yaogdu/agentledger/blob/main/docs/INSPECTOR.md

Install the Python/PyPI companion package and generate static HTML from an evidence bundle for a specific run. Run this on a developer, CI, support, or internal debugging machine after exporting evidence from a non-Python runtime.

```bash
pip install agentledger-inspector
agentledger inspector evidence ./evidence/<run_id> --html ./inspector.html
```

--------------------------------

### Install agentledger-langgraph and runtime with langgraph extra

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-langgraph/README.md

Install the base package and the runtime with the langgraph extra using pip. Use these commands to set up the package in a Python environment.

```bash
pip install agentledger-langgraph
pip install "agentledger-runtime[langgraph]"
```

--------------------------------

### v0.1 Deliverables: agentledger CLI Commands

Source: https://github.com/yaogdu/agentledger/blob/main/docs/IMPLEMENTATION_PLAN.md

Lists the CLI deliverables for the v0.1 milestone, showing commands to initialize, run an example, debug, replay, and inspect the ledger for a run.

```text
agentledger init
agentledger run examples/side_effect_idempotency
agentledger debug <run_id>
agentledger replay <run_id>
agentledger ledger <run_id>
```

--------------------------------

### Install optional agentledger-runtime adapters

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USAGE.md

Installs optional adapter extras for postgres, mysql, s3, langfuse, and inspector. For local development, use the corresponding -e ".[extra]" variants.

```bash
python3 -m pip install "agentledger-runtime[postgres]"
python3 -m pip install "agentledger-runtime[mysql]"
python3 -m pip install "agentledger-runtime[s3]"
python3 -m pip install "agentledger-runtime[langfuse]"
python3 -m pip install "agentledger-runtime[inspector]"
```

--------------------------------

### Run transient retry worker example

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USAGE.md

Commands to run a transient retry worker example with worker-run, serve, and plan modes. The serve command limits loops to 5 and the plan command specifies 2 replicas.

```bash
PYTHONPATH=src python3 -m agentledger --root .agentledger-worker worker-run examples/transient_retry
PYTHONPATH=src python3 -m agentledger --root .agentledger-worker worker serve examples/transient_retry --max-loops 5
PYTHONPATH=src python3 -m agentledger --root .agentledger-worker worker plan examples/transient_retry --replicas 2
```

--------------------------------

### Install agentledger-langgraph with sdk extra

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-langgraph/README.md

Install the optional sdk extra when combining with a concrete LangGraph version. Use this command to enable SDK features.

```bash
pip install "agentledger-langgraph[sdk]"
```

--------------------------------

### Install AgentLedger Python in a virtual environment

Source: https://github.com/yaogdu/agentledger/blob/main/docs/GETTING_STARTED.md

Install the Python runtime inside a project virtual environment and run the doctor command.

```bash
pip install agentledger-runtime
python -m agentledger doctor
```

--------------------------------

### Run OMP bridge demos in all runtimes

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Run the OMP bridge demo in each of the four runtime packages (Python, Go, TypeScript, Rust) from the repository root. Each command executes the corresponding example in its package directory.

```bash
PYTHONPATH=src python3 examples/omp_bridge/demo.py
cd go && go run ./examples/omp_bridge
cd typescript && node examples/omp_bridge/omp_bridge.js
cd rust && cargo run --example omp_bridge
```

--------------------------------

### Run cross-language three-minute demos

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USE_CASES.md

Runs the cross-language versions of the three-minute demo in Go, TypeScript, and Rust. Each command executes the same side-effect safety example in its respective language.

```bash
cd go && go run ./examples/three_minute_demo
```

```bash
cd typescript && node examples/three_minute_demo/three_minute_demo.js
```

```bash
cd rust && cargo run --example three_minute_demo
```

--------------------------------

### Try CLI flows with agentledger commands

Source: https://github.com/yaogdu/agentledger/blob/main/README.md

A series of CLI commands demonstrating various agentledger workflows: running an example, initializing, running, debugging, inspecting the ledger, resolving idempotency keys, replaying, exporting evidence, time travel, cost and failure reports, review checklists, tools manifest, and contract export. Each command uses PYTHONPATH=src and requires a run_id where indicated.

```bash
PYTHONPATH=src python3 examples/hello_world/hello.py
PYTHONPATH=src python3 -m agentledger init
PYTHONPATH=src python3 -m agentledger run examples/side_effect_idempotency
PYTHONPATH=src python3 -m agentledger debug --last --summary
PYTHONPATH=src python3 -m agentledger ledger <run_id> --pending
PYTHONPATH=src python3 -m agentledger ledger-resolve <run_id> <idempotency_key> --status failed-no-effect --reason "checked provider"
PYTHONPATH=src python3 -m agentledger debug <run_id> --json --include-diffs
PYTHONPATH=src python3 -m agentledger replay <run_id>
PYTHONPATH=src python3 -m agentledger evidence <run_id> --dir ./evidence/<run_id>
PYTHONPATH=src python3 -m agentledger evidence <run_id> --html ./evidence.html
PYTHONPATH=src python3 -m agentledger timetravel <run_id> --include-diffs --include-states --html ./time-travel.html
PYTHONPATH=src python3 -m agentledger cost report <run_id>
PYTHONPATH=src python3 -m agentledger failure report <run_id>
PYTHONPATH=src python3 -m agentledger review checklist <run_id> --fail-on-risk
PYTHONPATH=src python3 -m agentledger tools manifest --format agentledger --example examples/docs
PYTHONPATH=src python3 -m agentledger contract export
```

--------------------------------

### Minimal Rust runtime with simple_run

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Minimal runtime example for Rust. Defines an agent function, runs it with simple_run, and prints the run ID.

```rust
use agentledger::{simple_run, AgentContext, Result, State, Value};

fn agent(ctx: &mut AgentContext, input: State) -> Result<Option<Value>> {
    if let Some(name) = input.get("name") {
        ctx.write_state("message", Value::String(format!("hello {:?}", name)));
    }
    Ok(Some(Value::String("done".to_string())))
}

fn main() -> Result<()> {
    let mut input = State::new();
    input.insert("name".to_string(), "world".into());
    let result = simple_run(agent, input)?;
    println!("{}", result.run_id);
    Ok(())
}
```

--------------------------------

### Simple TypeScript API with simpleRun

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Simple API example for TypeScript/Node.js. Uses simpleRun with an initial state and prints the output.

```js
import { simpleRun } from './src/index.js';

const result = await simpleRun(async (_ctx, state) => ({ message: `hello ${state.name}` }), {
  initialState: { name: 'world' },
});
console.log(result.output);
```

--------------------------------

### Initialize module and get AgentLedger Go module

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Initializes a Go module if needed and fetches the AgentLedger Go module version v1.5.4. Must run inside a Go module.

```bash
go mod init your-module-name  # only if your project does not have go.mod yet
go get github.com/yaogdu/AgentLedger/go@v1.5.4
```

--------------------------------

### Run local worker smoke test

Source: https://github.com/yaogdu/agentledger/blob/main/docs/DISTRIBUTED_WORKERS.md

Local process smoke test that runs a worker in-process for the transient_retry example with a maximum of 5 loops. Useful for verifying a worker can start and execute locally.

```bash
PYTHONPATH=src python3 -m agentledger worker serve examples/transient_retry --max-loops 5
```

--------------------------------

### Core-only install: pip install agentledger-runtime

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_PACKAGING.md

Installs the core runtime package without any adapters.

```bash
pip install agentledger-runtime
```

--------------------------------

### Progressive Disclosure API Example (Python)

Source: https://github.com/yaogdu/agentledger/blob/main/docs/RUNTIME_SPEC.md

Shows the minimal Python API for creating and running an agent. The runtime state machine must not bypass leases, event logging, state version checks, policy, tool ledger, approval, sandbox, or evidence export.

```python
from agentledger import agent, run

@agent
def hello(ctx):
    return "hello world"

result = run(hello)
```

--------------------------------

### Install agentledger-sandbox-docker via pip

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-sandbox-docker/README.md

Install the Docker sandbox adapter package and the runtime with Docker extras. Requires Docker to be installed.

```bash
pip install agentledger-sandbox-docker
pip install "agentledger-runtime[docker]"
```

--------------------------------

### Repository layout

Source: https://github.com/yaogdu/agentledger/blob/main/README.md

Shows the top-level directory structure of the repository, including the Python, Go, TypeScript, and Rust runtime-core packages, plus tests, examples, docs, contracts, and migrations.

```text
src/agentledger/     Python reference runtime-core
tests/               unit, conformance, and integration-style tests
examples/            dependency-free examples and adapter facades
docs/                English documentation and runtime design docs
docs/zh/             Chinese primary reader path
contracts/           language-neutral runtime contract, semantic manifest, and conformance fixtures
go/                  Go native runtime-core package
typescript/          Node/TypeScript-compatible runtime-core package
rust/                Rust runtime-core package
migrations/          SQLite/Postgres/MySQL DDL and migration baselines
```

--------------------------------

### Initialize PostgresStore

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-postgres/README.md

Create a PostgresStore instance using configuration from environment variables and initialize it.

```python
from agentledger_postgres import PostgresStore, PostgresStoreConfig

store = PostgresStore(PostgresStoreConfig.from_env())
store.init()
```

--------------------------------

### Failure demo output paths

Source: https://github.com/yaogdu/agentledger/blob/main/examples/inspector/README.md

Example output paths printed by failure_demo.py. Open runs.html to verify the list page and failed-run-inspector.html to verify the single-run Event Stream, Failure Envelopes, lifecycle, replay plan, alerts, and causal graph panels.

```text
run index: /tmp/agentledger-inspector-failure-.../runs.html
failed run inspector: /tmp/agentledger-inspector-failure-.../failed-run-inspector.html
failed run json: /tmp/agentledger-inspector-failure-.../failed-run-inspector.json
```

--------------------------------

### Run Adoption Demos

Source: https://github.com/yaogdu/agentledger/blob/main/go/examples/README.md

Runs the three adoption demos from the go directory. The 3-minute demo shows crash/retry without duplicate external writes, the MCP governance demo shows descriptor annotations flowing into approval, sandbox metadata, idempotency, and audit evidence, and the OMP bridge demo maps normalized runtime records into AgentLedger evidence without depending on OMP internals.

```bash
cd go
go run ./examples/three_minute_demo
go run ./examples/mcp_governance
go run ./examples/omp_bridge
```

--------------------------------

### Run minimal agent with agentledger API

Source: https://github.com/yaogdu/agentledger/blob/main/README.md

Minimal API example that defines an agent function and runs it. The runtime creates a durable run, claims a leased step, records events, commits state atomically, and can export evidence.

```python
from agentledger import agent, run

@agent
def hello(ctx):
    return "hello world"

result = run(hello)
print(result.output)
print(result.run_id)
```

--------------------------------

### Minimal TypeScript runtime with Runtime.local

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Minimal runtime example for TypeScript/Node.js. Creates a local runtime, registers a tool, runs a single agent run, and prints the run ID from exported evidence.

```js
import { Runtime, exportEvidence } from './src/index.js';

const rt = await Runtime.local('.agentledger-ts/state.json');
rt.registerTool({
  name: 'docs.echo',
  func: async (args) => ({ echo: args.text }),
});

const { runId } = await rt.createRun({ input: 'hello' });
await rt.runOnce({
  runId,
  workerId: 'worker-ts',
  agentRole: 'Agent',
  agent: async (ctx, state) => {
    const result = await ctx.callTool('docs.echo', { text: state.input });
    await ctx.writeState('result', result);
  },
});

console.log(exportEvidence(rt.store, runId).run.run_id);
```

--------------------------------

### Initialize S3BlobStore from environment

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-s3/README.md

Create an S3BlobStore instance using configuration loaded from environment variables.

```python
from agentledger_s3 import S3BlobStore, S3BlobStoreConfig

blobs = S3BlobStore(S3BlobStoreConfig.from_env())
```

--------------------------------

### Run adoption demos

Source: https://github.com/yaogdu/agentledger/blob/main/rust/examples/README.md

Runs the adoption demos: three_minute_demo, mcp_governance, omp_bridge, and sqlite_evidence. The sqlite_evidence demo requires the sqlite-evidence feature and an output path argument.

```bash
cd rust
cargo run --example three_minute_demo
cargo run --example mcp_governance
cargo run --example omp_bridge
cargo run --features sqlite-evidence --example sqlite_evidence -- /tmp/agentledger-evidence
```

--------------------------------

### Initialize MySQLStore

Source: https://github.com/yaogdu/agentledger/blob/main/docs/MYSQL.md

Initialize the MySQL store using configuration from environment variables.

```python
from agentledger_mysql import MySQLStore, MySQLStoreConfig

store = MySQLStore(MySQLStoreConfig.from_env())
store.init()
```

--------------------------------

### Export Evidence as HTML Report

Source: https://github.com/yaogdu/agentledger/blob/main/docs/RUNTIME_SPEC.md

Exports evidence as a single static HTML report summarizing run metadata, final state, steps, Tool Ledger, approvals, artifacts, media artifacts, stream checkpoints, costs, and events. The report is static and does not start a long-running process.

```bash
PYTHONPATH=src python3 -m agentledger evidence <run_id> --html ./evidence.html
```

--------------------------------

### Install AgentLedger TypeScript npm package

Source: https://github.com/yaogdu/agentledger/blob/main/docs/GETTING_STARTED.md

Install the published npm package for TypeScript.

```bash
npm install agentledger-runtime
```

--------------------------------

### Install adapter packages directly: pip install agentledger-*

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_PACKAGING.md

Installs individual adapter packages directly, useful for explicit dependency locks, separate package mirrors, or independent adapter release governance.

```bash
pip install agentledger-postgres
pip install agentledger-mysql
pip install agentledger-s3
pip install agentledger-langgraph
pip install agentledger-mcp
pip install agentledger-otel
pip install agentledger-langfuse
pip install agentledger-sandbox-docker
pip install agentledger-inspector
```

--------------------------------

### Run demo with custom output directory

Source: https://github.com/yaogdu/agentledger/blob/main/examples/showcase/duplicate_side_effect_crash/README.md

Run the demo with a custom output directory. Set AGENTLEDGER_SHOWCASE_ROOT to choose where the generated HTML files are written.

```bash
AGENTLEDGER_SHOWCASE_ROOT=/tmp/agentledger-showcase PYTHONPATH=src python3 examples/showcase/duplicate_side_effect_crash/demo.py
```

--------------------------------

### Install agentledger-inspector via pip

Source: https://github.com/yaogdu/agentledger/blob/main/packages/agentledger-inspector/README.md

Install the inspector package alone or with the runtime's inspector extra.

```bash
pip install agentledger-inspector
pip install "agentledger-runtime[inspector]"
```

--------------------------------

### Run Postgres conformance via namespace

Source: https://github.com/yaogdu/agentledger/blob/main/docs/POSTGRES.md

Equivalent conformance command through the Postgres namespace.

```bash
AGENTLEDGER_POSTGRES_DSN=postgresql://user:password@localhost:15432/database \
AGENTLEDGER_POSTGRES_SCHEMA=agentledger \
PYTHONPATH=src python3 -m agentledger postgres conformance
```

--------------------------------

### Verify local Go repo with tests and conformance

Source: https://github.com/yaogdu/agentledger/blob/main/docs/LANGUAGE_QUICKSTART.md

Runs tests and the conformance command from the local repository to verify the Go implementation.

```bash
cd go
go test . ./cmd/agentledger-go
go run ./cmd/agentledger-go conformance
```

--------------------------------

### Run runtime benchmark and language parity check

Source: https://github.com/yaogdu/agentledger/blob/main/docs/BENCHMARKS.md

Run the full runtime benchmark and language parity check for release evidence. The first command executes the benchmark with 20 iterations and writes output to /tmp/agentledger-benchmark; the second verifies language conformance. Use this for runtime-core or cross-language releases, and attach or summarize benchmark.md in release notes when the release changes runtime semantics, failure handling, Inspector/debug output, evidence consumers, adapters, or language parity.

```bash
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 scripts/benchmark_runtime.py --iterations 20 --output-dir /tmp/agentledger-benchmark
python3.11 scripts/check_language_parity.py
```

--------------------------------

### Run Adoption Demos

Source: https://github.com/yaogdu/agentledger/blob/main/typescript/examples/README.md

Run the three adoption demos from the typescript/ directory. The 3-minute demo shows crash/retry without duplicate external writes; the MCP governance demo shows descriptor annotations flowing into approval, sandbox metadata, idempotency, and audit evidence; the OMP bridge demo maps normalized runtime records into AgentLedger evidence without depending on OMP internals.

```bash
cd typescript
node examples/three_minute_demo/three_minute_demo.js
node examples/mcp_governance/mcp_governance.js
node examples/omp_bridge/omp_bridge.js
```

--------------------------------

### Run doctor without installing (PYTHONPATH=src)

Source: https://github.com/yaogdu/agentledger/blob/main/README.md

Runs the doctor command without installing the package by setting PYTHONPATH to the src directory.

```bash
PYTHONPATH=src python3 -m agentledger doctor
```

--------------------------------

### Kubernetes deployment pattern

Source: https://github.com/yaogdu/agentledger/blob/main/docs/DISTRIBUTED_WORKERS.md

Recommended initial Kubernetes deployment pattern: Deployment with replicas and command, PreStop for graceful shutdown, readiness checks for config/store connectivity, and liveness for process health. Kubernetes should not be the source of run state.

```text
Deployment:
  replicas: N
  command: agentledger worker serve <agent-entrypoint>
  env: StateStore, BlobStore, policy, sandbox config

PreStop:
  allow graceful SIGTERM handling

Readiness:
  check config and store connectivity outside runtime-core

Liveness:
  supervisor-level process health, not run correctness
```

--------------------------------

### Configure DSN and run migrations

Source: https://github.com/yaogdu/agentledger/blob/main/docs/MYSQL.md

Configure the MySQL DSN and run migration status and migration up commands with the mysql dialect.

```bash
export AGENTLEDGER_MYSQL_DSN="mysql://agentledger:password@127.0.0.1:3306/agentledger"
python3 -m agentledger migrate status --dialect mysql
python3 -m agentledger migrate up --dialect mysql
```

--------------------------------

### Run Demo with Custom Output Directory

Source: https://github.com/yaogdu/agentledger/blob/main/examples/three_minute_demo/README.md

Runs the demo with a custom output directory by setting AGENTLEDGER_DEMO_ROOT to /tmp/agentledger-three-minute.

```bash
AGENTLEDGER_DEMO_ROOT=/tmp/agentledger-three-minute PYTHONPATH=src python3 examples/three_minute_demo/demo.py
```

--------------------------------

### Initialize Go module and add AgentLedger dependency

Source: https://github.com/yaogdu/agentledger/blob/main/docs/GETTING_STARTED.md

Initialize a Go module if needed and add the AgentLedger Go library as a dependency.

```bash
go mod init your-module-name  # only if your project does not already have go.mod
go get github.com/yaogdu/AgentLedger/go@v1.5.4
```

--------------------------------

### Production-pilot checklist for Postgres adapter

Source: https://github.com/yaogdu/agentledger/blob/main/docs/POSTGRES.md

Verify these operational requirements before using the adapter for serious pilot workloads. The checklist covers schema isolation, migration, backup/restore, connection pooling, timeouts, least-privilege roles, and conformance runner passes.

```text
schema name is isolated per deployment environment
migration rollout and rollback process is documented
backup/restore can recover run, step, event, ledger, approval, cost, and artifact refs
connection pool sizing and transaction timeout policy are defined
statement timeout and lock timeout are configured by deployment policy
least-privilege database role owns only AgentLedger schema objects
StateStoreConformanceRunner passes against the target database
WorkerConformanceRunner passes against the target database
multi-worker claim/recovery behavior is tested under expected concurrency
```

--------------------------------

### Precise error message when adapter package is missing

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_PACKAGING.md

When an adapter package is not installed, the shim should fail with this precise message, directing the user to install the appropriate extra.

```text
Postgres support moved to agentledger-postgres.
Install with: pip install "agentledger-runtime[postgres]"
```

--------------------------------

### Run Temporal Bridge Demo

Source: https://github.com/yaogdu/agentledger/blob/main/examples/temporal_bridge/README.md

Run the demo from the repository root. Expected behavior includes two activity attempts, one external action, replay summary, failure summary, evidence directory, and Inspector HTML path.

```bash
PYTHONPATH=src python3 examples/temporal_bridge/demo.py
```

--------------------------------

### Instantiate S3BlobStore with S3BlobStoreConfig

Source: https://github.com/yaogdu/agentledger/blob/main/docs/STORAGE.md

Shows how to instantiate S3BlobStore with an S3BlobStoreConfig. The client parameter is optional and useful for tests or enterprise wrappers; omit endpoint_url for AWS S3.

```python
from agentledger import S3BlobStore, S3BlobStoreConfig

blobs = S3BlobStore(
    S3BlobStoreConfig(
        bucket="agentledger-runs",
        prefix="prod/blobs",
        endpoint_url="http://minio.local:9000",  # omit for AWS S3
    ),
    client=my_s3_client,  # optional; useful for tests or enterprise wrappers
)
```

--------------------------------

### Dependency-free Policy YAML Example

Source: https://github.com/yaogdu/agentledger/blob/main/docs/SECURITY_ENTERPRISE.md

Example dependency-free YAML policy for local enterprise governance testing. Defines defaults and role-based tool/risk restrictions. Evaluated through the normalized PolicyRequest -> PolicyDecision contract in 1.1.0.

```yaml
version: 1
defaults:
  low: allow
  medium: allow
  high: deny
roles:
  ExecutorAgent:
    allow_tools:
      - github.create_issue
    deny_tools:
      - shell.exec
    deny_risk:
      - destructive
```

--------------------------------

### Native runtime loop steps

Source: https://github.com/yaogdu/agentledger/blob/main/docs/MULTI_LANGUAGE.md

Lists the minimal native runtime loop steps each language (Go, TypeScript, Rust) should implement first, covering run creation, event logging, tool calls, checkpointing, storage, validation, and replay.

```text
create run
claim leased step
append event
call runtime-managed tool
write Tool Ledger entry
commit checkpoint
reopen local durable store
write/read local content-addressed blobs
validate tool input/output schemas
run local worker/service loop
export evidence
replay without side effects
```

--------------------------------

### Install AgentLedger Inspector packages

Source: https://github.com/yaogdu/agentledger/blob/main/docs/INSPECTOR.md

Install the Inspector via the core CLI or as an optional companion package. The agentledger-inspector package only re-exports the read model and data source API; the CLI entry point remains agentledger.

```bash
pip install "agentledger-runtime[inspector]"
pip install agentledger-inspector
```

--------------------------------

### Inspect Postgres and MySQL runtime databases

Source: https://github.com/yaogdu/agentledger/blob/main/docs/INSPECTOR.md

Use these commands for server-side StateStore deployments. They use read-only store wrappers and do not run migrations or create tables. Ensure database credentials have read-only permissions.

```bash
agentledger inspector run <run_id> --backend postgres --dsn "$AGENTLEDGER_POSTGRES_DSN" --schema agentledger --blob-root .agentledger/blobs --html ./inspector.html
agentledger inspector run <run_id> --backend mysql --dsn "$AGENTLEDGER_MYSQL_DSN" --database agentledger --blob-root .agentledger/blobs --html ./inspector.html
agentledger inspector runs --backend postgres --dsn "$AGENTLEDGER_POSTGRES_DSN" --schema agentledger --html ./runs.html
agentledger inspector runs --backend mysql --dsn "$AGENTLEDGER_MYSQL_DSN" --database agentledger --html ./runs.html
```

--------------------------------

### Recommended Smoke Commands for Media and Stream Adapters

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_CERTIFICATION.md

Recommended smoke commands to run for media and stream adapter certification. Execute these in order to verify basic media stream, managed tool, manifest generation, and conformance checks.

```bash
PYTHONPATH=src python3 examples/media_stream/basic_media_stream.py
PYTHONPATH=src python3 examples/media_stream/managed_tool.py
PYTHONPATH=src python3 -m agentledger tools manifest --format agentledger --example examples/media_stream
PYTHONPATH=src python3 -m agentledger conformance
```

--------------------------------

### Run BlobStore conformance check

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_CERTIFICATION.md

Run the required conformance check for a BlobStore backend. Replace <backend> with the actual backend name.

```bash
PYTHONPATH=src python3 -m agentledger blob conformance --backend <backend>
```

--------------------------------

### Run drill with temporary dependencies

Source: https://github.com/yaogdu/agentledger/blob/main/docs/BACKUP_RESTORE.md

Runs the same drill script using uv with temporary psycopg dependency, avoiding permanent installation.

```bash
UV_CACHE_DIR=/tmp/agentledger-uv-cache uv run --no-project --with "psycopg[binary]" --python python3 python scripts/drill_postgres_backup_restore.py --output-dir /tmp/agentledger-postgres-backup-restore-drill
```

--------------------------------

### Tool Ledger status machine

Source: https://github.com/yaogdu/agentledger/blob/main/docs/RUNTIME_SPEC.md

Shows the allowed status transitions for ledger entries, starting from RESERVED and ending in terminal states.

```text
RESERVED
  -> RUNNING
  -> SUCCEEDED
  -> FAILED_NO_EFFECT
  -> PENDING_VERIFICATION
  -> COMPENSATED
```

--------------------------------

### Run the three-minute demo

Source: https://github.com/yaogdu/agentledger/blob/main/docs/USE_CASES.md

Runs the smaller side-effect safety demo for cross-language parity.

```bash
PYTHONPATH=src python3 examples/three_minute_demo/demo.py
```

--------------------------------

### SQLite default implementation features

Source: https://github.com/yaogdu/agentledger/blob/main/docs/STORAGE.md

Describes the default SQLite implementation characteristics, suitable for local development, examples, tests, and small single-node deployments.

```text
zero external services
WAL mode
foreign keys enabled
busy timeout enabled
automatic migrations
```

--------------------------------

### Run local adapter validation script

Source: https://github.com/yaogdu/agentledger/blob/main/docs/ADAPTER_VALIDATION.md

Runs the local adapter validation script using the project's virtualenv and the optional dependencies installed earlier.

```bash
bash scripts/validate_adapters_local.sh --output-dir /tmp/agentledger-adapter-validation
```

--------------------------------

### Run full benchmark with language conformance

Source: https://github.com/yaogdu/agentledger/blob/main/docs/BENCHMARKS.md

Runs the full benchmark suite from the repository root with 20 iterations, writing results to /tmp/agentledger-benchmark. This is the default release-gate command; it enables language conformance commands for Python, Go, TypeScript, and Rust.

```bash
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 scripts/benchmark_runtime.py --iterations 20 --output-dir /tmp/agentledger-benchmark
```