Skip to content

AionCore CLI Capabilities

Jump to bottom
zk edited this page Jul 9, 2026 · 4 revisions

AionCore CLI Capabilities

Language: English | 中文

This page documents the AionCore agent-facing CLI contract. It is intended for agent / skill automation, not as a human-oriented interactive CLI manual.

Positioning

aioncore exposes two kinds of command surfaces:

  • Agent-facing CLI: used by AionUi built-in skills, assistants, scheduled tasks, and agent conversations.
  • Internal / developer CLI: used by AionCore itself, team MCP plumbing, packaging, and developer diagnostics.

The agent-facing CLI is designed to be stable, machine-readable, and safe:

  • Stable command names.
  • Business input is passed through stdin JSON, not flags.
  • stdout returns a JSON envelope.
  • stderr returns a stable single-line error code.
  • Sensitive fields are redacted by default.
  • Runtime context is injected by AionUi; skills should not discover ports, build ad hoc HTTP clients, or inspect processes.

Quick Start

Top-level capability index:

aioncore capabilities

capabilities does not require the AionUi runtime environment. It is safe to use for discovering which agent-facing domains the current binary supports.

The top-level index only answers: which agent-facing domains are supported, and where each domain's detailed contract lives. It does not expand every command field, so the output stays compact and stable.

Detailed domain contracts:

aioncore config capabilities
aioncore diagnose capabilities

capabilities vs help

Traditional --help or help output is primarily for humans. Its formatting can change with clap, wording, and layout, so it should not be treated as a stable skill input.

capabilities is the agent-facing contract:

  • It returns a stable JSON envelope.
  • It declares domains, command paths, input modes, selectors, runtime requirements, and safety boundaries.
  • Skills can read it at runtime instead of hardcoding every field forever in SKILL.md.
  • New domains can be registered first, then consumed by skills through their contracts.

Therefore, --help can remain a developer convenience, while skills and agent automation should rely on capabilities.

Capability Discovery Model

Use two-level discovery:

Level Command Purpose
Top-level index aioncore capabilities Lists agent-facing domains, modes, risks, safety boundaries, and detailed contract commands
Domain contract aioncore config capabilities Lists config commands, stdin fields, selectors, write/readback behavior, and redaction rules
Domain contract aioncore diagnose capabilities Lists diagnose commands, stdin fields, read-only boundaries, and the controlled HTTP escape hatch

When adding a new agent-facing domain, register it in top-level capabilities first, then provide its own <domain> capabilities.

Runtime Context

AionUi injects runtime context into agent conversations. The CLI should not rely on skills to discover processes, ports, or database paths.

Examples in this page use aioncore for readability. Inside a managed AionUi agent runtime, agents should invoke the injected helper binary from AIONUI_HELPER_BIN; for example, aioncore config capabilities maps to "$AIONUI_HELPER_BIN" config capabilities.

Core environment variables:

Variable Description
AIONUI_HELPER_BIN Path to the current aioncore executable; skills should invoke the CLI through it
AIONUI_BASE_URL Base URL of the running aioncore HTTP server
AIONUI_CONVERSATION_ID Current agent conversation id; the primary context anchor
AIONUI_USER_ID Current user id
AIONUI_LOG_DIR Optional log directory, mainly used by diagnose logs tail

Core rules:

  • conversation_id: "current" resolves from AIONUI_CONVERSATION_ID.
  • assistant_id: "current" resolves through the assistant associated with the current conversation.
  • user_id: "current" resolves from AIONUI_USER_ID.
  • Do not introduce a complex selector DSL; keep simple string selectors.

The same context model should cover one-on-one conversations, team chats, and scheduled tasks. As long as the agent runtime injects the current conversation id, the CLI uses the same conversation_id: "current" semantics. If a runtime does not provide conversation context, commands that depend on the current conversation should return a stable error instead of letting the skill guess assistant or backend state.

Input Contract

Except for no-input commands, the agent-facing CLI uses stdin JSON:

aioncore config assistants get <<'JSON'
{
  "assistant_id": "current",
  "locale": "en-US"
}
JSON

Why stdin JSON:

  • Agents do not need to remember which fields are flags and which fields are request bodies.
  • Complex objects, long text, MCP transport config, and provider config use one input style.
  • Sensitive values do not appear in argv.
  • The CLI layer can resolve selectors, validate payloads, and redact data before forwarding.

Business parameters should not be modeled as command-line flags. Flags are appropriate for CLI execution control, not agent-facing business fields.

Output and Error Contract

On success, stdout returns a JSON envelope:

{
  "success": true,
  "data": {},
  "meta": {
    "schema_version": 1
  }
}

Field contract:

Field Description
success Whether the CLI command completed successfully
data Command result data, usually from backend API data
meta CLI metadata, such as schema version, resolved selectors, readback, and escape hatch markers

On failure:

  • stdout does not emit a success envelope.
  • stderr emits a stable single-line error.
  • The process exits with a non-zero code.

Error format:

<DOMAIN>_<CODE> command="<command path>" field="<field>" status="<http-status>": <message>

Examples:

CONFIG_ENV_MISSING command="config context" field="AIONUI_CONVERSATION_ID": missing required environment variable
DIAGNOSE_PAYLOAD_INVALID command="diagnose http get" field="path": path must start with /health or /api/
CAPABILITIES_STDOUT_WRITE_FAILED command="capabilities": failed to write JSON output

Error messages must not include prompts, secrets, MCP headers, environment values, file contents, or raw provider requests/responses.

Agent-facing Domains

config

Purpose: manage AionUi desired state. This domain can write configuration.

Detailed contract:

aioncore config capabilities

Main capabilities:

Subdomain Capability
context Read current user, conversation, assistant, and base URL
assistants list/get/create/update/delete/import/state
assistants rule read/write/delete assistant rule
assistants skill read/write/delete assistant skill content
skills list/info/paths/import/delete/scan
skills external-paths list/add/remove external skill paths
skills market enable/disable skill market
mcp servers list/get/create/update/delete/toggle/import
mcp oauth check-status/login/logout/authenticated
providers list/create/update/delete/detect-protocol/fetch-models/health-check
settings get/patch backend settings
settings client get/put client preferences
agents list/enable/overrides/custom agent management
cron jobs list/get/create/update/delete/run/skill state
cron current list/create/update scheduled task for current conversation

Safety rules:

  • Write operations should perform read-before-write or readback.
  • Provider keys, MCP headers, env values, and prompt/rule content are redacted by default.
  • After changing an assistant rule, tell the user that the new rule usually applies to new conversations; the current conversation may still use its startup snapshot.
  • Do not keep the old cron-helper; scheduled tasks are managed through config cron current ... or config cron jobs ....

diagnose

Purpose: read-only troubleshooting for AionUi runtime state. This domain must not write configuration.

Detailed contract:

aioncore diagnose capabilities

Main capabilities:

Subdomain Capability
context Read current diagnostic runtime context
health Read backend health/version/build metadata
overview Aggregate health, providers, MCP, cron, and running conversations
conversations list List conversations and runtime summaries
conversations get Read one conversation with stuck/waiting hints
conversations messages Read conversation messages, optionally filtering errors
providers summary Summarize provider model health
mcp summary Summarize MCP servers and enabled-with-zero-tools state
cron summary Summarize scheduled jobs and failing last runs
teams summary Summarize teams and member conversation state
logs tail Tail aioncore logs with errors_only/conversation_id support
http get Controlled GET escape hatch

diagnose http get preserves the old troubleshooting helper's raw GET capability, but only as a controlled escape hatch:

  • GET only.
  • The path must be /health or /api/....
  • Redacted by default.
  • Output may be truncated.
  • Marked as escape_hatch: true in capabilities.
  • Skills should prefer named commands and use the escape hatch only for uncovered read-only diagnostics.

Internal / Developer Subcommands

These are not agent-facing automation contracts:

Command Purpose
doctor Human/developer self-check for agent backend availability
mcp-bridge Internal stdio-to-TCP bridge for team MCP
mcp-team-stdio Internal team MCP stdio server
prepare-managed-resources Packaging helper for managed runtime resources

They may appear in non_agent_subcommands in top-level capabilities, but skills should not treat them as configuration or diagnostic capabilities.

Relationship with HTTP APIs

CLI names may reference HTTP resources, but they should not mechanically expose HTTP paths.

Principles:

  • CLI commands are named by agent-facing domains, not by code modules or current HTTP paths.
  • HTTP is an implementation detail; the CLI contract is the stable agent-facing interface.
  • Common capabilities should become named commands.
  • Raw HTTP is allowed only through explicit controlled escape hatches, such as diagnose http get.

Examples:

  • Assistant rule endpoints may live under /api/skills/assistant-rule/*, but the CLI should expose them as config assistants rule ... because rules are part of assistant behavior definition.
  • Current-conversation cron task management is exposed through config cron current ..., not the old cron-helper.

Checklist for New Agent-facing Domains

When adding a new domain similar to config or diagnose, complete all of the following:

  1. Register the domain in aioncore capabilities.
  2. Provide <domain> capabilities with a full agent-readable contract.
  3. Define the domain mode: read-only, read-write, or a more specific risk model.
  4. Use stdin JSON consistently; do not use business flags.
  5. Use a consistent stdout JSON envelope.
  6. Use stable stderr error codes.
  7. Define selector rules and prefer reusing conversation_id: "current".
  8. Define sensitive field redaction policy.
  9. Add E2E coverage for each critical path.
  10. Update the related built-in skill to call the CLI only, with no Python, process discovery, or handwritten HTTP.

Skill Usage Guidance

Recommended built-in skill flow:

  1. If unsure what the current aioncore supports, call:

    aioncore capabilities

  2. When configuring AionUi, call:

    aioncore config capabilities

  3. When diagnosing AionUi, call:

    aioncore diagnose capabilities

  4. Execute specific commands according to the domain contract.

Skills should not:

  • Inspect aioncore processes.
  • Probe ports.
  • Call Python helpers directly.
  • Build complex JSON through shell string assembly.
  • Print provider or MCP secrets to the user.

Current Coverage

This wiki currently covers these CLI capabilities:

  • Top-level: capabilities
  • Config: config capabilities, config context, assistants, skills, MCP, providers, settings, agents, cron
  • Diagnose: diagnose capabilities, diagnose context, health, overview, conversations, providers, MCP, cron, teams, logs, controlled HTTP GET

If future domains are added, such as channel, office, workspace, or a more specific repair domain, update the top-level capability index first, then add the matching domain contract and skill documentation.

Clone this wiki locally