elizaos--eliza/plugins/plugin-cli/AGENTS.md

@elizaos/plugin-cli

CLI framework infrastructure for elizaOS agents: command registration, a TTY-aware progress reporter, and duration/byte formatting helpers.

Purpose / role

This plugin provides the scaffolding for building a Commander-based CLI on top of an Eliza agent runtime. It ships a module-level command registry that other plugins or host apps populate at startup, plus buildProgram / runCli entry points that assemble the final CLI. It is opt-in — load it explicitly via the agent's plugin list. It registers no actions, providers, services, evaluators, or routes; its value is its exported API.

Plugin surface

The cliPlugin export (default) registers:

Field	Value
name	"cli"
actions	[]
providers	[]
services	[]
routes	[]
config	CLI_NAME, CLI_VERSION (see below)
init	Logs count of registered commands; no persistent side effects
dispose	Returns immediately

All real functionality is in the exported API (registry + utils), not in the plugin object's hooks.

Exported API

src/index.ts — entry point

• cliPlugin — the Plugin object; default export.
• buildProgram(options?) — constructs a Command with all registered commands attached; returns the Commander root.
• runCli(argv?, options?) — calls buildProgram, then program.parseAsync. Pass argv to override process.argv.
• Re-exports Command from commander for convenience.

src/registry.ts — command registry

Module-level Map<string, CliCommand> — shared across all imports in the same process.

Export	Purpose
registerCliCommand(cmd)	Add a CliCommand; warns and replaces on duplicate name
unregisterCliCommand(name)	Remove by name; returns boolean
getCliCommand(name)	Look up by name
listCliCommands()	All commands sorted by priority (lower = earlier, default 100)
registerAllCommands(ctx)	Called by buildProgram; iterates sorted list, calls each register(ctx)
clearCliCommands()	Empties the registry — test helper only
defineCliCommand(name, description, register, options?)	Factory for CliCommand; accepts optional aliases and priority
addSubcommand(parent, name, description)	Thin wrapper: parent.command(name).description(description)

src/utils.ts — utilities

Export	Purpose
DEFAULT_CLI_NAME	"elizaos"
DEFAULT_CLI_VERSION	"1.0.0"
resolveCliName(argv?)	Derives CLI name from process.argv[1] (strips path + extension)
createDefaultDeps()	Returns CliDeps (console.log, console.error, process.exit)
createProgressReporter(deps, options?)	TTY-aware spinner; falls back to plain log when not a TTY
withProgress(deps, message, fn)	Runs an async function with spinner; succeeds/fails reporter automatically
parseDurationMs(input)	Parses "1s", "5m", "2h", "7d", bare ms numbers → ParsedDuration
parseTimeoutMs(input?, defaultMs)	parseDurationMs with a fallback default
formatDuration(ms)	ms → human string ("1.5s", "3.2m", "1.0h")
formatBytes(bytes)	Bytes → "1.4 MB" etc.
formatCliCommand(command, options?)	Formats elizaos [--profile P] [--env E] <command>
isInteractive()	stdin.isTTY && stdout.isTTY

src/types.ts — shared types

CliContext, CliCommand, CliRegistrationFn, CliPluginConfig, CliLogger, ProgressReporter, ProgressOptions, CliDeps, ParsedDuration, CommonCommandOptions.

Layout

plugins/plugin-cli/
  src/
    index.ts      Plugin object, buildProgram, runCli, re-exports
    registry.ts   Module-level command registry (Map-backed)
    utils.ts      Progress reporter, duration/byte helpers, CLI name resolution
    types.ts      All shared interfaces and type aliases
  __tests__/
    core-test-mock.ts   vitest setupFile (vi.mock of @elizaos/core logger)
  package.json
  tsconfig.json
  biome.json
  vitest.config.ts

Commands

bun run --cwd plugins/plugin-cli build          # tsc compile → dist/
bun run --cwd plugins/plugin-cli build:watch    # tsc --watch
bun run --cwd plugins/plugin-cli dev            # alias for build:watch
bun run --cwd plugins/plugin-cli test           # vitest run
bun run --cwd plugins/plugin-cli lint           # biome check --write --unsafe
bun run --cwd plugins/plugin-cli lint:check     # biome check (read-only)
bun run --cwd plugins/plugin-cli format         # biome format --write
bun run --cwd plugins/plugin-cli format:check   # biome format (read-only)
bun run --cwd plugins/plugin-cli typecheck      # tsgo --noEmit

Config / env vars

Declared in agentConfig.pluginParameters but not read from process.env by any source file. Pass values directly to buildProgram / runCli as call-site options:

Variable	Required	Default	Description
CLI_NAME	No	"elizaos"	CLI binary name shown in help output
CLI_VERSION	No	"1.0.0"	Version string shown by --version

Pass via buildProgram({ name: "myapp", version: "2.0.0" }) or runCli(argv, { name, version }). The init function does not read the config parameter (_config is intentionally unused).

How to extend

Add a new CLI command

1. Call defineCliCommand + registerCliCommand before buildProgram runs (typically at module load time or in your plugin's init):

import { defineCliCommand, registerCliCommand } from "@elizaos/plugin-cli";

registerCliCommand(
  defineCliCommand(
    "my-cmd",
    "Does something useful",
    (ctx) => {
      ctx.program
        .command("my-cmd")
        .description("Does something useful")
        .option("--flag", "a flag")
        .action((opts) => {
          const runtime = ctx.getRuntime?.();
          // ...
        });
    },
    { priority: 50 }, // lower = registered earlier
  ),
);

2. The command appears in elizaos --help automatically once buildProgram is called.

Use the progress reporter in a command

import { createDefaultDeps, withProgress } from "@elizaos/plugin-cli";

const deps = createDefaultDeps();
await withProgress(deps, "Doing work", async () => {
  await someLongOperation();
});

Conventions / gotchas

• The command registry is module-level state (a Map). In a single Node/Bun process all imports share the same registry; in tests always call clearCliCommands() in beforeEach / afterEach to avoid cross-test pollution.
• buildProgram iterates listCliCommands() at call time. Register all commands before calling buildProgram.
• registerCliCommand silently replaces on duplicate name (with a logger.warn). Use distinct names to avoid accidental overrides.
• The plugin object itself has no persistent resources: dispose returns immediately and init only logs.
• createProgressReporter writes directly to process.stdout using ANSI escapes when isTTY; it degrades to plain deps.log in non-TTY environments (CI, piped output).
• parseDurationMs returns { valid: false, ms: 0 } on bad input — always check valid before using ms.
• Build output goes to dist/ (.gitignored). The package ships only dist/ — no src/ in the published tarball.

⛔ NON-NEGOTIABLE — evidence, trajectories & real end-to-end tests

The binding, repo-wide standard is AGENTS.md. Read it. Nothing in this package is done until it is proven done — a reviewer must confirm it works without reading the code, from the artifacts you attach. This applies to every feature, fix, refactor, and chore here. "Tests pass" is not proof; "CI is green" is not proof.

• Record AND read model trajectories. Capture the actual inputs and outputs of the model from a live LLM — not the deterministic proxy, not a mock: the prompt, the providers/context, the raw model output, every tool/action call, and the result. Then open the trajectory and review it by hand. A captured-but-unread trajectory is not evidence (packages/scenario-runner/bin/eliza-scenarios run <scenario> --report <out>).
• Real, full-featured E2E — no larp. Every feature ships detailed end-to-end tests that drive the real path end to end. Not the happy "front door" only: cover error paths, edge/empty/invalid input, concurrency, roles/permissions, and adversarial input. A test that asserts against a mock/stub/fixture standing in for the thing under test does not count. If the real model/device/chain/connector/account is hard to reach, make it reachable — that is the work, not an excuse to mock. If the existing tests here are shallow or mocked, fixing them is part of your change.
• Screenshots + logs at every phase, plus a complete walkthrough video/run-through of the entire feature or view, start to finish (bun run test:e2e:record).
• Manually review every artifact the change touches — never just the green check: client logs (console + network), server logs ([ClassName] …), the model trajectories in and out, before/after full-page screenshots, and the domain artifacts listed below for this package.
• No residuals. No shortcuts. The goal is not "done" — it is everything done. Clear every blocker by the hard path: build the real architecture, stand up the real model/device/service, actually test it. Never leave a TODO, a stub, a stepping-stone, or a "follow-up." When unsure, research thoroughly, weigh the options, and ship the best, highest-effort, production-ready version. Keep going until every possibility is exhausted.

Artifacts → attached inline in the PR (MP4 video, JPG screenshots, logs in <details>); attach each evidence type or explicitly mark it N/A with a reason — never leave it blank. If develop moved and changed behavior, re-capture evidence; stale proof is worse than none.

Capture & manually review for this package — CLI / tooling:

• The real command/flow invocation transcript (args in, stdout/stderr, exit code) and the artifacts it generated (files, scaffolds, manifests, screenshots/recordings).
• Failure paths: bad args, missing deps, partial state, permission/network errors.
• A recording/log of the actual run end to end — not a unit test of one helper.
• Any model interaction captured as a live trajectory and reviewed.