lgs-cli

name: lgs-cli description: Use for the lgs / logos-scaffold CLI as a whole — bootstrap a project, run setup/build/deploy/localnet/wallet/doctor/report, diagnose CLI errors, or adopt scaffold in an existing project. Covers the full CLI surface, the .scaffold/ state layout, and error → recovery patterns. Entry point that routes into lez-template, lez-framework-template, or basecamp once project context is identified.

Using logos-scaffold

logos-scaffold (alias lgs — functionally identical) is a Rust CLI for bootstrapping LEZ (Logos Execution Zone) program_deployment projects in standalone mode. This skill is the entry point any time the user asks Claude to use scaffold itself — either to create / drive a project, or to recover from a failure.

When to Use

• The user wants to create a new LEZ project (lgs new, lgs create).
• The user wants to run any lgs / logos-scaffold subcommand against an existing project (setup, build, deploy, localnet, wallet, spel, basecamp, doctor, report).
• A scaffold command failed and needs diagnosis (use the playbook + error table below).
• The user wants to adopt scaffold in an existing Rust/LEZ project (lgs init) or migrate an older scaffold.toml.

Once a project exists on disk, also pull in the matching template / integration skill:

• lez-template — bare LEZ standalone (Rust + risc0). Identify by absence of framework = "lez-framework" in scaffold.toml and presence of methods/guest/src/bin/*.rs.
• lez-framework-template — declarative macros (Anchor parallel). Identify by framework = "lez-framework" in scaffold.toml plus crates/lez-client-gen/ and idl/.
• basecamp — lgs basecamp … lifecycle for Logos module projects (capture / install / launch with profile-isolated state). Activates additionally on any lgs basecamp invocation, presence of [basecamp.modules] in scaffold.toml, or .scaffold/basecamp/profiles/. Independent of the template skills — can layer onto either template or stand alone in an external module project.

Command Map

lgs and logos-scaffold are interchangeable. Group by purpose:

First Success Path

From a scratch directory (per templates/default/README.md):

lgs new my-app
cd my-app
lgs run
lgs wallet -- check-health

lgs run chains setup → build → IDL → localnet → topup → deploy. The step-by-step path (setup / localnet start / build / deploy / topup) lives in the repo README under "Step-by-step (optional)" — reach for it to debug or learn a single phase.

Checkpoint at any time:

lgs localnet status
lgs doctor

Adopting an Existing Project

cd my-existing-project
lgs init      # writes scaffold.toml, creates .scaffold/, appends .gitignore
lgs setup

init does not touch Cargo.toml or src/. Re-run init to migrate older scaffold.toml schemas (legacy [basecamp] keys move to [repos.basecamp] / [modules.*]; legacy url on [repos.{lez,spel}] is dropped) or to refresh the shipped AI skills. Already-current configs succeed and leave scaffold.toml unchanged.

.scaffold/ Layout

Everything scaffold writes lives under .scaffold/ inside the project. Treat this directory as the source of truth for runtime state, not the user's home.

Non-vendored projects share a cache root: <cache_root>/repos/<name>/<pin>/... (configurable at lgs new via --cache-root).

Debugging Playbook

Apply in order. Stop as soon as the issue is identified.

1. lgs doctor — prints actionable checks and next steps. Use --json for parsing. Doctor inspects: required binaries (git/rustc/cargo/lsof/ps/kill, docker or podman), LEZ + spel repo presence and pin alignment, sequencer + wallet + spel binaries, port 3040 reachability, runtime state file, wallet network config, wallet --version and check-health.
2. lgs localnet status [--json] — distinguishes managed, stale_state, foreign listener, and missing.
3. lgs localnet logs --tail 200 — tail recent sequencer output.
4. cat .scaffold/logs/sequencer.log — full log if --tail isn't enough.
5. lgs report --tail 500 — produce a shareable .tar.gz under .scaffold/reports/. Always inspect the archive before sharing publicly (tar -tzf <path> to list contents).

Error → Recovery Table

Environment Overrides

JSON Outputs

Use --json whenever piping to other tools:

lgs localnet status --json    # { tracked_pid, listener_present, ownership, ready }
lgs doctor --json             # { status, summary, checks, next_steps }
lgs deploy --program-path "<path>" --json   # { status, program, tx?, program_id? }
lgs basecamp doctor --json

lgs deploy --json only produces structured JSON when combined with --program-path. On the discovery path, --json is silently accepted but ignored.

DOGFOODING Cross-Reference

The canonical scenarios in DOGFOODING.md:

• D1–D6 — default template (bootstrap, localnet/doctor, deploy variants, wallet, report, runner interaction).
• L1–L4 — lez-framework template (bootstrap, IDL regen, client regen, deploy + counter).
• E1–E2 — CLI surface (help/version/error quality, advanced new flags).
• B1–B5 — basecamp (setup, modules+install+launch, p2p, clean-slate, build-portable).

When reproducing a failure, name the matching scenario in the bug report.

Key Rules

• Never rm -rf .scaffold/wallet/ — it contains keys; lgs report deliberately excludes it.
• Never edit [basecamp.modules] while lgs basecamp modules is running. Otherwise hand-edits in that section are preserved across re-runs.
• Always lgs localnet stop before any destructive reset; otherwise scaffold may leave a stale PID.
• Always inspect .scaffold/reports/*.tar.gz (tar -tzf <path>) before sharing publicly. Sanitisation is best-effort, not absolute.
• Prefer project-local binaries via lgs wallet -- ... and lgs spel -- ... over global installs. Nothing scaffold builds is added to PATH on purpose.
• Don't assume --json is structured for every command; it's structured only where the table above says so (status, doctor, deploy w/ --program-path, basecamp doctor).
• Project-scoped commands run outside a project root produce a clear Not a logos-scaffold project ... error — don't try to work around it; cd into the project or lgs init.