CLI

Command Behavior
agent-apps Bootstrap + invoke main skill entry point
agent-apps <skill> [--arg key=value...] Bootstrap + invoke skill by name or path with args
./skill.skill.md #!/usr/bin/env agent-apps — run file directly

No subcommands. Every positional argument is a ToolRef. Tools like skill-compile are regular skills invoked as agent-apps skill-compile --ref foo.

Unknown --key value flags (flags not recognized by the CLI parser) are automatically added to skill args. This means agent-apps help --ref shell is equivalent to agent-apps help --arg ref=shell. Repeated unknown flags accumulate into arrays: --ref a --ref b → { ref: ["a", "b"] }. Known flags (--arg, --arg-json, --config, --config-json, --local, --local-json, --global, --global-json, --log, --dry-run, --help, --version, -q, -v) are consumed by the CLI; everything else becomes an arg.

All CLI args are strings. Before invoking a skill, the CLI coerces string values to the types declared in the tool's params: "42" → 42 for type: number, "true" → true for type: boolean, and JSON-parseable strings for type: array or type: object. Integer-keyed objects (e.g., --arg 0=a --arg 1=b) are converted to arrays when params declares type: array.

Runtime Flags

Runtime flags control CLI behavior:

  • --log key=value — configure logging. Repeatable and additive. Keys: level (trace|debug|info|warn|error|silent), scope (comma-separated tag names, e.g., pipeline,agent), reporter (agent|pipeline|events|cascade|tools|json|status|mcp-log).
  • --log (bare, no value) — print available scopes and reporters, then exit.
  • --log full — enable full log output (all scopes, all events).
  • --log <scope> (bare scope name, no =) — shorthand for --log scope=<scope>. E.g., --log agent is equivalent to --log scope=agent.
  • -v, -vv, -vvv, -vvvv — shorthand for --log level=warn, --log level=info, --log level=debug, --log level=trace.
  • -q — shorthand for --log level=silent.
  • --dry-run — print config diagnostics and exit.
  • --help — print usage information and exit.
  • --version — print the installed version and exit.

Log reporters provide specialized output formats. The default reporter writes to stderr with color-coded levels. Additional reporters are activated via --log reporter=<name> and run alongside the default:

Reporter Description
json Structured JSON output — one JSON object per log event.
agent Agent-focused output — model turns, tool calls, errors.
pipeline Pipeline-focused output — invocations, chain entries, timing.
events Event bus activity — subscribe, emit, handler dispatch.
cascade Cascade resolution — authority, inherit chain, merge strategies.
tools Tool resolution — cache hits/misses, search paths, loading.
status Minimal status line — current tool and phase.
mcp-log MCP server logging — forwards log events to connected MCP clients.

These are consumed by the CLI before reaching the tool pipeline, so they never collide with tool args.

Alias Flags

There are currently no alias flags. The --strict flag was removed when strict mode was replaced by automatic compatibility mode for SKILL.md folder-skills.

Config Overrides

Three tiers of key=value overrides, using dot notation for nesting:

  • --config key=value — pre-cascade globals. Sets values on globals.config directly (e.g., cwd, workspace, library). These are foundation values needed before any tool runs.
  • --config-json <json> — same as --config but accepts a JSON object. Repeatable. Keys are merged into config overrides.
  • --local key=value — cascade injection scoped to the project's main skill authority. Only merges into the cascade when the tool's authority matches globals.config.mainTool. Use this for project-level config that shouldn't leak into hub dependencies or external packages.
  • --local-json <json> — same as --local but accepts a JSON object. Repeatable.
  • --global key=value — cascade injection applied unconditionally to all invocations regardless of authority. Use this for truly global concerns like model selection.
  • --global-json <json> — same as --global but accepts a JSON object. Repeatable.
  • --arg key=value — skill argument. Repeatable. Repeated keys accumulate into arrays: --arg ref=a --arg ref=b → { ref: ["a", "b"] }.
  • --arg-json <json> — skill arguments as a JSON object. Repeatable. Keys are merged into args.

Values starting with { or [ are parsed as JSON, enabling structured data on the command line:

--config 'paths=[{"external":"./vendor"}]'
--config 'paths.0={"external":"./vendor"}'

Invalid JSON falls back to a plain string.

Dot notation creates nested objects: --local model.region=us-east-1 sets { model: { region: "us-east-1" } }. Numeric segments create arrays: --config paths.0=./skills.

Flags can appear before or after the skill name:

agent-apps --local model.id=sonnet hello --name World
agent-apps hello --name World --log level=trace --global model.region=us-west-2

Environment Variables

Environment variables follow the same three-tier model with prefixes:

  • AGENT_APPS_CONFIG_* — pre-cascade globals
  • AGENT_APPS_LOCAL_* — authority-scoped cascade injection
  • AGENT_APPS_GLOBAL_* — universal cascade injection

Double underscores delimit nesting; single underscores become hyphens:

AGENT_APPS_CONFIG_CWD=/other/project
AGENT_APPS_LOCAL_MODEL__REGION=us-east-1    # → { model: { region: "us-east-1" } }
AGENT_APPS_GLOBAL_MODEL__ID=sonnet          # → { model: { id: "sonnet" } }

CLI overrides take priority over environment variables within the same tier.

Additional env vars:

  • AGENT_APPS_LOG_LEVEL — set log level (trace, debug, info, warn, error, silent).
  • AGENT_APPS_LOG_SCOPE — filter log output by tag (comma-separated, e.g., pipeline,agent).
  • AGENT_APPS_DRY_RUN — enable dry-run mode (any truthy value).

--log overrides take priority over environment variables.

Ask AI