中文版 | English

ae-cli

ae-cli is the command-line client for the ThinkingAI AgenticEngine (AE) platform. It provides stable, structured interfaces for both AI Agents and human operators across analytics, experimentation, metadata, tracking, Engage, DataOps, knowledge bases, Agent resources, and system administration.

The CLI is designed around:

• JSON-first output that Agents can inspect and act on.
• Host-scoped authentication and environment configuration.
• Curated commands for common workflows plus Capability Gateway access for long-tail operations.
• Explicit validation, dry-run, and confirmation contracts for safer writes.
• Exact CLI and Skills version synchronization with the connected AE environment.

Requirements

• Node.js 20 or later.
• Access to the npm registry for CLI installation.
• Access to GitHub when installing Skills initially or when the local Skills fallback cannot be used.

Installation

For setup through Codex, Claude Code, Cursor, or another terminal-capable AI Agent, see the AE CLI installation and upgrade guide.

Install the public CLI and Agent Skills:

npm install -g @thinkingai/ae-cli
npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y

The Skills teach supported coding Agents, including Claude Code, Codex, Cursor, and similar tools, how to discover and call ae-cli.

Install optional, approved scenario Skills with an interactive category picker:

npx skills@latest add ThinkingAIAgenticEngine/scenario-skills

See the scenario-skills repository for version-specific and non-interactive installation.

Log in to an AE environment:

ae-cli auth login --host https://your-ae-host.example.com
ae-cli auth status

Use the AE URL supplied by your AgenticEngine administrator. If no Host is configured, ae-cli guides existing customers to obtain that URL first. Only users without an AgenticEngine environment are directed to request a trial.

Environment-Bound Updates

Each AE environment returns the exact aeCliVersion it expects. Use the unified update command to install that CLI version and its matching Skills:

ae-cli update
ae-cli update --dry-run

ae-cli update installs the exact version required by the active host rather than npm latest. It synchronizes Skills from the installed npm package first and uses the matching GitHub tag only as a fallback.

Starting with the 6.0.37 and 6.1.9 release lines, ordinary business commands can automatically upgrade or downgrade the CLI to the host-required version. After a successful synchronization, the old process exits with AE_CLI_VERSION_SYNCED; re-run the original command so it executes with the new CLI and Skills. Installation failures are reported without replacing the business command's JSON output.

Useful controls:

# Use another configured host
ae-cli update --host https://another-host.example.com

# Install an explicit version
ae-cli update --target 6.1.9

# Skip compatibility checks for one command
ae-cli --no-update-check capability list --domain analysis

Quick Start

# Open the interactive environment manager
ae-cli config

# Or manage environments non-interactively
ae-cli config list
ae-cli --format table config list
ae-cli config current
ae-cli config add https://your-ae-host.example.com --label production --use
ae-cli config use production

# Discover capabilities exposed by the host
ae-cli capability list --domain analysis
ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list

# Validate, preview, and execute
ae-cli capability validate analysis.dashboard.list --input '{"project_id":1}'
ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'

# Filter structured output
ae-cli capability list --domain analysis --jq '.data.capabilities[] | .id'

Command Surface

Run ae-cli --help or ae-cli <command> --help for the authoritative command list.

Command or domain	Purpose
analysis	Reports, dashboards, ad-hoc analysis, drilldowns, details, alerts, and analysis schemas
experiment	Atlas experiments, reports, traffic layers, buckets, Features, metrics, and operation logs
analysis-meta	Event/property metadata, metrics, virtual metadata, tracking governance, and project configuration
analysis-governance	Asset search, lineage, impact analysis, and governance operations
metadata	Capability-backed data-table and property operations
tracking	Tracking-plan lifecycle, SDK samples, checks, ingestion diagnostics, code generation, and bundled wiki
engage-flow, engage-task, engage-setting, engage-scene, engage-activity, engage-workbench	Engage flows, tasks, settings, strategies, activities, and workbench operations
community	Community posts, comments, topics, sentiment, livestream, and report workflows
dataops_repo, dataops_datatable, dataops_flow, dataops_ide, dataops_integration, dataops_operations	Data warehouse, data-table, flow, IDE, integration, and operations workflows
kb	Knowledge-base lifecycle, LLM query, and deterministic index/grep/read retrieval
agent	Agents, automations, models, MCP servers, Skills, attachments, credentials, and sandbox tools
system	Root/admin operations for members, sandboxes, shared tools, models, usage, quotas, and IM channels
team	Agent Team lifecycle and TeamRun execution, chat, result, and artifact workflows
capability	Capability discovery, schema inspection, validation, dry-run, and generic execution
auth, config	Host-scoped authentication and multi-environment configuration
api	Raw authenticated HTTP requests for diagnostic or transitional use
sync	Push or pull local Skills and MCPs to/from the Agent application
model	Switch the current workspace model inside an Agent sandbox
update	Synchronize CLI and Skills to the version required by the current host

Capability Gateway

Capability Gateway is the preferred entry point for operations that do not need a dedicated curated command:

ae-cli capability list --domain analysis --project-id 1
ae-cli capability search "report list" --domain analysis
ae-cli capability inspect analysis.report.list
ae-cli capability validate analysis.report.list --input input.json
ae-cli capability dry-run analysis.report.list --input input.json
ae-cli capability run analysis.report.list --input input.json

--input accepts inline JSON, a JSON file path, @<path>, or - for stdin.

Use validate while fixing complex nested input. Use dry-run when you need the final risk, output mode, cancellation support, or delete confirmation preview. Do not stack validate and dry-run for the same final payload by default; dry-run already validates it.

Gateway-backed features follow the Capability command admission rules. Common workflows may have curated commands; long-tail capabilities remain dynamically discoverable.

Authentication and Environments

Credentials are stored per host. Switching environments does not reuse a token from another host. Run ae-cli config in a terminal to add, activate, rename, or remove environments interactively. For scripts and agents, use the non-interactive subcommands:

ae-cli auth login --host https://host-a.example.com
ae-cli auth status --host https://host-a.example.com
ae-cli auth logout --host https://host-a.example.com

ae-cli config list
ae-cli config current
ae-cli config add https://host-b.example.com --label staging
ae-cli config use staging
ae-cli config rename staging pre-production
ae-cli config remove pre-production --yes

<env> accepts either an exact URL or a unique label. The active environment is clearly marked in the interactive manager and in config list. Removing an active environment is rejected while other environments remain; switch first so replacement is explicit. config set-host remains available as a compatibility command that adds or updates a host and activates it.

Login uses a cross-platform device-code flow. Use --no-browser when the environment cannot open a browser. Trial guidance is emitted only when no Host is configured; normal commands and authentication flows for configured environments do not display it.

Output and Safety

Commands return a stable envelope:

{
  "ok": true,
  "data": {},
  "_notice": {}
}

• --format json is the default and is recommended for Agents.
• --format table is available for supported human-facing list commands.
• --jq <expr> applies jq 1.8 filtering to the business payload before the output envelope is printed.
• --validate normalizes Capability Gateway input without business execution.
• --dry-run previews an operation without executing its business logic.
• --yes skips interactive confirmation for explicitly marked high-risk writes.
• _notice may include host compatibility or update guidance without changing successful business data.

JSON flags generally accept inline JSON, @file, a file path, or - for stdin. Check command help for the exact accepted forms.

Knowledge Bases

Manage the server-side knowledge-base lifecycle:

ae-cli kb +new --scope company --name engineering-handbook --description "Team docs"
ae-cli kb +add --name engineering-handbook --files '["./docs/guide.md","https://example.com/page"]'
ae-cli kb +schema --name engineering-handbook
ae-cli kb +compile --name engineering-handbook
ae-cli kb +status --name engineering-handbook
ae-cli kb +ask -q "How is the sandbox configured?"
# Submit only, poll later:
ae-cli kb +ask -q "Another question" --no-wait
ae-cli kb +ask-status --execution-id <id>

External Agents can use deterministic retrieval without a server-side LLM:

ae-cli kb +list
ae-cli kb +index --sources '[{"scope":"company","name":"engineering-handbook"}]'
ae-cli kb +grep -q "sandbox config" --sources '[{"scope":"company","name":"engineering-handbook"}]' --paths '["wiki/sandbox.md"]'
ae-cli kb +read --source '{"scope":"company","name":"engineering-handbook"}' --path "wiki/sandbox.md"

Agent and System Administration

The agent domain manages user-visible Agent resources:

ae-cli agent +list-agents
ae-cli agent +list-models
ae-cli agent +list-mcps
ae-cli agent +list-skills
ae-cli agent +list-automations
ae-cli agent +list-attachments

The system domain calls administrative /api/admin/** endpoints and requires a root or agent_admin role:

ae-cli system +list-members --status enabled
ae-cli system +list-sandboxes
ae-cli system +get-usage-summary --days 30
ae-cli system +list-quota-rules
ae-cli system +list-channels

Authorization is always enforced by the server. Do not retry or bypass a permission error.

Agent Skills

The npm package includes the same skills/ directory used by the public repository:

Skill	Scope
ae-capability	Capability discovery and generic invocation
ae-analysis, ae-analysis-global	Analysis, audience, metadata, governance, and multi-cluster workflows
ae-experiment	Atlas experiment, Feature, metric, traffic-layer, and report workflows
ae-metadata	Capability-backed metadata data-table operations
ae-engage	Engage operations and workflow guidance
ae-dataops	Data warehouse, flow, IDE, integration, and operations
ae-community	Community analysis and reporting
ae-kb	Knowledge-base lifecycle and retrieval
ae-agent, ae-system, ae-team	Agent resources, administration, and TeamRun workflows
ae-generate-tracking-plan, ae-generate-tracking-code	Tracking-plan and tracking-code generation
ae-data-integration-helper	SDK and LogBus2 integration guidance

Reinstall all public Skills with:

npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y

Development

git clone https://github.com/ThinkingAIAgenticEngine/ae-cli.git
cd ae-cli
npm install
npm run build
node dist/index.js --help

Run from source during development:

npm run dev -- --help

Core structure:

src/
├── core/          # auth, config, clients, compatibility, version sync
├── framework/     # command registration, lifecycle, output, errors
├── api/           # raw authenticated API access
└── commands/      # business domains and CLI utilities
skills/            # Agent Skills shipped with the npm package
self-check/        # release and documentation consistency checks
test/, tests/      # command, contract, and regression tests

Useful verification commands:

npm run build
npm run qa-changed
npm run self-check
npm run check:release
npm run verify:experiment-tools
npm run verify:update-check
npm run verify:version-sync

Changelog

• English changelog
• 中文更新日志

License

MIT