YYLO Ledger CLI Reference
Use yy ledger from the controller, or yylo-ledger standalone. Ledger exposes compatible flat task commands and native ID-first record|task|wiki|pdr|workflow|artifact groups, subject to installed help. yy kanban is a labelled compatibility alias for the same controller-routed runtime.
Retrieve any Record first
Preflight yy ledger get --help. When it advertises universal retrieval, use
yy ledger get RECORD_ID -f json for tasks, documents, PDRs and artifacts without
knowing the type. If installed get is task-only, use
yy ledger record get RECORD_ID -f json after checking native help; if absent,
stop for an upgrade. Do not try each type until one works.
New generated IDs use task_, doc_, or artifact_ for storage kind only;
existing IDs remain unchanged. New PDRs are artifact/report, while historical
document/pdr Records remain readable through the same command. Exact reads
include hot and archived Records in the selected project. When no ID is known,
start with yy ledger record search --projection summary --limit 20 -f json;
use explicit --scope archive|all for cold discovery.
Read references/retrieval.md for bounded content,
--content byte retrieval, PDR examples, compatibility and refusal handling.
Small readable non-task payloads are included by default; Record metadata alone
is not proof that payload bytes were retrieved. Typed commands remain for
mutation and specialized rendering/validation.
Supported task contract
- Preflight installed
yy ledger --versionandyy ledger --help; command help is authoritative for the selected runtime. - Use universal get for reads, flat task commands for task bookkeeping, and the controller's
yy tasklifecycle for managed delivery. Use dedicated wiki, workflow, and artifact skills for typed mutations rather than guessing arguments. - New operational PDRs, contracts, plans, reports, receipts, and evidence belong in typed Artifact Records, not product documentation, task bodies/responses, or new
.juno_task/specsfiles. - If a required native group is absent, fail closed and request a Ledger upgrade. Never invoke mutable source directly or write Ledger store files by hand.
- Read current task state before mutation, preserve mutation receipts where offered, and never bypass controller routing or lifecycle state with direct file edits.
- Normal discovery is hot-only unless an explicit cold-archive command is used.
Opt-in cross-project routing
Cross-project access is disabled by default. The source .juno_task/config.json must set kanbanRegistry.enabled: true and explicitly list allowedProjects; environment overrides are YYLO_LEDGER_REGISTRY_ENABLED and YYLO_LEDGER_REGISTRY_ALLOWED_PROJECTS. Register with yy ledger project add ALIAS --path /absolute/project, then route any command with --project ALIAS. The destination wrapper/runtime remains authoritative, and routing failures never fall back to the source board.
Legacy Task compatibility commands
CREATE — Add a new task
bashyy ledger create "Task description here" --status backlog --tags feature,backend
Options: --status (backlog|todo|in_progress|done), --tags (comma/space-separated), --blocked-by (task IDs), --related-tasks (task IDs)
LIST — Browse tasks with summary stats
bashyy ledger list --limit 5 --sort asc yy ledger list --status todo --sort asc yy ledger list --status todo,in_progress --limit 10
SEARCH — Find tasks by criteria
bashyy ledger search --status todo --tag backend --limit 10 yy ledger search --body "OAuth" --open yy ledger search --commit abc123
Filters: --status, --tag, --body, --response, --commit, --open (no agent_response), --recent, --exclude (exclude tags)
GET — Universal Record read; task details retain dependency and related-task compatibility
bashyy ledger get TASK_ID
MARK — Update status with required response message
bashyy ledger mark in_progress --id TASK_ID --response "Starting work on this" yy ledger mark done --id TASK_ID --response "Completed: implemented X, tested Y" --commit abc123def yy ledger mark todo --id TASK_ID --response "Reopening: found regression"
Required: --id and --response. Optional: --commit (recommended for done).
UPDATE — Modify task fields
bashyy ledger update TASK_ID --status todo --tags backend,urgent yy ledger update TASK_ID --commit abc123def yy ledger update TASK_ID --response "Additional context"
ARCHIVE — Soft delete (preserves data, sets status to archive)
bashyy ledger archive TASK_ID
Immutable cold archive packs
Normal list, search, ready, and order are deliberately hot-only. Exact get TASK_ID transparently resolves a hot task or a read-only archived task; use history TASK_ID explicitly for its ledger. Discover cold tasks only with bounded, projected archive-search output:
bashyy ledger archive-search --tag backend --before 2026-01-01 --limit 20 --projection metadata
Before archive maintenance, preflight the installed version/help and obtain explicit owner authorization. The repository and index must be clean, and reports must be durable new paths outside the repository:
bashyy ledger --version yy ledger archive-pack plan --status done,archive --older-than 90d --max-tasks 1000 --target-bytes 26214400 --hard-max-bytes 47185920 --report /external/receipts/archive-plan.json # Independently inspect selected IDs, revisions, source HEAD, policy, and plan hash. yy ledger archive-pack create --plan /external/receipts/archive-plan.json --report /external/receipts/archive-create.json yy ledger archive-pack doctor yy ledger doctor
A stale plan or selected-task/worktree conflict must fail closed: discard the plan, resolve the conflict, and plan again. Never automate archival, edit/append packs or manifests, restore/reopen an archived ID, use force/lossy controls, or enumerate archive files directly. Create follow-up work as a new hot task related to the archived ID. Production archival, push/deploy, and post-deploy E2E each require separate authorization; agents must not infer it from implementation approval.
Dependency Management
DEPS — View, add, or remove task dependencies
bash# View dependency info (blockers, dependents, priority score) yy ledger deps TASK_ID # Add blockers (TASK_ID cannot start until BLOCKER1 and BLOCKER2 are done) yy ledger deps add --id TASK_ID --blocked-by BLOCKER1 BLOCKER2 # Remove a blocker yy ledger deps remove --id TASK_ID --blocked-by BLOCKER1
Cycle detection prevents circular dependencies automatically.
READY — Tasks with all blockers satisfied (safe to work on)
bashyy ledger ready yy ledger ready --tag backend --limit 5
Returns tasks where status is backlog/todo/in_progress AND all blocked_by tasks are done/archive.
ORDER — Topological sort of open tasks respecting dependencies
bashyy ledger order yy ledger order --scores
Use for determining safe parallel execution order.
Body Markup for Inline Dependencies
Declare dependencies and relations directly in task body text:
[blocked_by]TASK_ID[/blocked_by] — This task is blocked by TASK_ID [blocked_by]ID1, ID2[/blocked_by] — Blocked by multiple tasks [task_id]RELATED_ID[/task_id] — Reference a related task [task_id]ID1 ID2[/task_id] — Multiple related tasks
These are parsed automatically when the task is created/updated.
Merge (Multi-Directory Consolidation)
When tasks get scattered across subdirectories:
bash# First produce and review a deterministic plan yy ledger merge ./sub1/.juno_task ./sub2/.juno_task --into ./.juno_task \ --dry-run --plan-file /external/ledger-merge-plan.json # Apply only that reviewed plan and retain its receipt yy ledger merge ./sub1/.juno_task ./sub2/.juno_task --into ./.juno_task \ --apply-plan /external/ledger-merge-plan.json \ --receipt-file /external/ledger-merge-receipt.json
Output Formats
Legacy task formats: -f json, -f ndjson, -f xml, -f table.
list/search/ready/order -f json emits one object containing tasks and
summary, including empty results. Use --raw for compact JSON or -f json -p
for indented JSON. Without a format, output defaults to pretty JSON; --raw
makes it compact, while --pretty selects human-readable task rendering.
NDJSON emits one task per line and no summary record (zero bytes when empty).
For non-empty list/search/ready, NDJSON/XML/table summaries go to stderr;
order retains no stderr summary. Empty XML emits an empty <tasks> document.
--raw accepts JSON/NDJSON only and cannot be combined with --pretty.
Unsupported combinations fail before task enumeration. Style flags may appear
before or after these collection commands; the canonical wrapper preserves
this contract and keeps runtime diagnostics on stderr.
These source contracts require a matching Ledger release; skill source delivery
alone does not install or activate that runtime.
Best Practices
- Task sizing: Create tasks small enough to complete in one iteration without filling the context window
- Status flow: backlog → todo → in_progress → done (or archive for abandoned tasks)
- Always include
--responsewhen usingmark— document what you did and how you tested it - Attach commits: Use
--commit HASHwhen marking done, thenupdate TASK_ID --commit HASHto link the git history - Use
readybefore starting work to find unblocked tasks - Use
order --scoresto plan parallel execution pipelines - Use
[blocked_by]markup in task body when creating tasks that depend on others - Use
[task_id]markup in task body to cross-reference related tasks - Use
get TASK_IDto see full task details including resolved dependency and related task info - Concurrent features are supported — start each selected task with
yy task start TASK_ID; each gets a dedicated product worktree, whileyy mergeserializes only target updates
Canonical Controller Routing
YYLO Ledger mutation resolves the controller in this order: explicit JUNO_TASK_ROOT, repository-local registration, then the current project root. Diagnose before orchestration with .juno_task/scripts/controller_resolver.py --cwd "$PWD" --operation kanban. The resolver may bootstrap or idempotently confirm a registration, but changing an existing controller requires yy migrate registration plan followed by a separately authorized apply. Explicit/registered path or branch errors fail closed—YYLO Ledger never switches Git branches or falls back silently.
Run YYLO Ledger and workflows from the controller. A task checkout may implement/test but routes task/session writes to that controller. An integration-owner checkout stays clean and refuses Kanban/orchestration/session writes in strict mode; launch from the controller and pass the product checkout separately as TASK_ROOT.
Environment Variables
JUNO_TASK_ROOT— Explicit canonical controller/task-storage root (not the productTASK_ROOT)JUNO_CONTROLLER_BRANCH— Expected controller branch for environment-based routingJUNO_WORKSPACE_ROLE—controller,task, orintegration-ownerJUNO_WORKSPACE_ENFORCEMENT—off,warn, orstrictJUNO_DEBUG=true— Show diagnostic messagesJUNO_VERBOSE=true— Show informational messagesJUNO_KANBAN_LIST_BODY_TRUNCATE_CHARS=N— Override list body truncation (default: 1200)
User-facing Record results
After creation, update, discovery, or handoff, report the Record kind/profile, actual immutable Record ID, and actual Ledger slug from the returned Record or a native get readback. Never invent a slug from the title or confuse it with the ID. If the selected API omits a field, say it is unavailable rather than fabricate it. IDs remain authoritative for relations and lifecycle operations; slugs aid discovery.
$ARGUMENTS
