Skip to content

LazyAI Commands

Session Management

Track AI agent sessions with full audit trail.

Start a Session

lazyai-cli session start "Implement user authentication"

Output:

✅ Session started: ses_1779583480
   Goal: Implement user authentication
   Started: 2026-05-24T00:44:40Z

List Sessions

lazyai-cli session list

Output:

Sessions:
---------
🟢 ses_1779583480 | Implement user authentication | 2026-05-24T00:44:40Z
🔴 ses_1779582575 | Fix login bug | 2026-05-24T00:29:34Z

Show Session Details

lazyai-cli session show ses_1779583480

Output:

Session: ses_1779583480
Goal: Implement user authentication
Status: active
Started: 2026-05-24T00:44:40Z

Dispatches:
  [completed] implementer: Implement auth middleware
  [completed] reviewer: Review auth implementation

End a Session

lazyai-cli session end ses_1779583480

Output:

✅ Session ended: ses_1779583480
   Ended: 2026-05-24T00:54:25Z

Health Checks

Validate your environment before starting work.

Run Doctor

lazyai-cli doctor

Doctor reports setup integrity first, then these 6 environment checks:

  1. sqlite3 dependency
  2. git dependency
  3. jq dependency (optional warning)
  4. bash dependency
  5. ollama provider on localhost:11434 (warning if unavailable)
  6. Disk space usage

JSON Output

lazyai-cli doctor --json

Useful for CI/CD pipelines and automated monitoring.

Setup and Configuration Commands

These setup-core commands cover common maintenance tasks around an initialized LazyAI project.

Manage MCP Servers

Enable or disable cataloged MCP servers, then compile per-tool configs.

lazyai-cli server list
lazyai-cli server add ai-memory
lazyai-cli compile

Configure Local Defaults

Create and update .opencode/config.yaml.

lazyai-cli config init
lazyai-cli config set notifications.enabled true

Create an Artifact

Generate agents, skills, prompts, commands, templates, or hooks.

lazyai-cli create agent release-reviewer --description "Reviews release readiness" --no-interactive

Manage Sidecars

Point optional docs/specs/plans directories at workspace, project, or global scope. --scope defaults to project when omitted; a workspace-scope config is created by running sidecar init --scope workspace from the shared ancestor directory — there is no separate registration step and no sidecar attach command.

lazyai-cli sidecar init --scope project --path ../shared-docs
lazyai-cli sidecar status

Import an Existing Setup

Import an existing tool setup into LazyAI-managed form.

lazyai-cli import ../existing-setup --tool opencode --preview

Migrate Older LazyAI or ai-setup Config

Move older LazyAI or ai-setup files into the current canonical format.

lazyai-cli migrate ~/old-ai-setup --preview

Update the CLI Binary

Check or install a GitHub Release for lazyai-cli.

lazyai-cli update-self --check

Inspect Setup Inventory

Scan or plan supported setup targets without starting runtime execution.

lazyai-cli setup --scan
lazyai-cli setup --dry-run --global --all

Audit Trail

Immutable hash-chained ledger for tracking all actions.

Initialize Ledger

lazyai-cli ledger init

Creates .specify/ledger.jsonl with a genesis entry.

Append Events

lazyai-cli ledger append dispatch "agent=implementer task=auth"
lazyai-cli ledger append session_start "goal=Implement auth"
lazyai-cli ledger append validation "status=pass agents=8"

Verify Integrity

lazyai-cli ledger verify

Verifies: - Hash chain continuity - Entry hash correctness - No tampering detected

Show Entries

lazyai-cli ledger show 10

Shows last 10 entries with truncated hashes.

Validation

Check agent and skill file structure.

Validate Agents

lazyai-cli validate agents

Checks: - YAML frontmatter present (error) - # System Prompt heading present (error) - Managed marker present (warning) - Section heading after # System Prompt present (warning)

Validate Skills

lazyai-cli validate skills

Checks: - Confirm SKILL.md directory structure - Verify required YAML frontmatter fields (name, description) - Verify quick reference sections are present and non-empty where required - Validate referenced scripts for skills with command actions are resolvable

Runtime migration note

Legacy task, workflow, orchestration, mcp-setup, and obsolete eval CLI commands were removed during the runtime refactor. Repository harness scripts are not replacements for those product commands.

See ../migration/fortnite-orchestrator-removal.md and ../concepts/product-boundaries.md for replacements, rollback guidance, and current command ownership.

Agent Message Bus

SQLite-based messaging between agents.

Send a Message

lazyai-cli message send implementer "Need help" "Can you review the auth code?" --priority high

Receive Messages

lazyai-cli message recv implementer

Note: This marks all unread messages for the agent as read and shows the 10 most recent messages.

Broadcast

lazyai-cli message broadcast "All hands" "System update at 2pm"

Git Integration

Sync Changes

lazyai-cli git sync

Safety note: This command stages and commits ALL changes in the current repository after showing the file list and asking for confirmation. Use --force to skip the confirmation prompt.

Backup

Create Backup

lazyai-cli backup create

Restore from Backup

lazyai-cli backup restore <backup-file>

Safety note: This overwrites current LazyAI data with the backup contents. Use --force to skip the confirmation prompt.

Secrets

Store a Secret

lazyai-cli secret set <name> <value>

Retrieve a Secret

lazyai-cli secret get <name>

Safety note: Secrets are stored locally using the OS keychain when available, or a fallback file in ~/.lazyai/secrets/ (not encrypted at rest). Do not use for production credentials.

Notifications

Configure Webhook

lazyai-cli notify config --webhook https://hooks.example.com/notify

Safety note: The webhook URL is stored in the local config file. Ensure the URL is trusted and uses HTTPS.

Send a Test Notification

lazyai-cli notify test

Metrics

Export Metrics

lazyai-cli metrics export

Writes metrics.prom (Prometheus format) in the current directory. Use -o to specify a different path.

Generate Dashboard

lazyai-cli metrics dashboard

Writes dashboard.html in the current directory. Use -o to specify a different path.

Completion

Generate shell completion scripts.

# Bash
source <(lazyai-cli completion bash)

# Zsh
source <(lazyai-cli completion zsh)

# Fish
lazyai-cli completion fish | source

Typical Workflow

# 1. Check environment
lazyai-cli doctor

# 2. Start session
lazyai-cli session start "Implement feature X"

# 3. Work with agents...
# (agent dispatches are automatically logged)

# 4. Validate changes
lazyai-cli validate agents

# 5. Check audit trail
lazyai-cli ledger verify

# 6. End session
lazyai-cli session end ses_1234567890