AgentEarth CLI

AgentEarth CLI is an agent-first command line interface that helps AI agents discover, inspect, and execute AgentEarth tools from any shell.

Commands

ae login [--api-key-stdin]
ae recommend [--limit <1-50>] -- "<task>"
ae list [@query.json|-|'<json>']
ae detail <tool_name>
ae execute --request request.json
ae execute "<tool_url>" '@params.json'  # legacy
ae update

Use ae on Unix-like shells and ae.cmd on Windows. For @file input, PowerShell requires quotes such as ae.cmd list '@query.json', while CMD uses ae.cmd list @query.json without single quotes.

ae update runs npm view @agentearth.ai/cli version --json in real time. Applying an update runs npm install -g @agentearth.ai/cli@latest, then verifies the active ae --version. The three external steps are limited to 30 seconds, 5 minutes, and 10 seconds respectively. If npm registry version discovery fails, the command returns version_check_failed. Business commands do not perform background version checks or emit update notices.

Install And Login

npm install -g @agentearth.ai/cli
printf '%s' '<API_KEY>' | ae login --api-key-stdin

--api-key-stdin is the first-login path used by the website installation prompt. It validates at most 8 KiB of input without placing the supplied Key in the ae process arguments. Plain ae login remains available when AGENTEARTH_API_KEY is already configured.

After successful validation, process the CLI JSON next_actions in ascending order. The first action requires the agent to persist the same validated Key as AGENTEARTH_API_KEY in the current agent host so future ae processes inherit it. The second action provides the bundled skill source_dir; read SKILL.md, copy the entire directory into the current agent skills directory, verify its completion_condition, and reload when required. Report on_blocked instead of claiming completion when the host cannot perform an action. The CLI never returns or stores the Key and keeps no credential, telemetry, update, or lock state on disk.

Website installation prompt:

Install AgentEarth CLI, log in with this API key: {sk-XXXX}, then follow the CLI output to install the bundled AgentEarth skill into your current agent host.
Set this API key in the AGENTEARTH_API_KEY environment variable for your current agent host.

Commands:
npm install -g @agentearth.ai/cli
printf '%s' '<API_KEY>' | ae login --api-key-stdin

Agent Workflows

Use ae list when the task category is already clear:

list -> detail -> execute

For filtered list queries, agents should write the query JSON to a file and pass it with @query.json:

{"keyword":"image","page":1,"page_size":20}

ae list @query.json

Use ae recommend when the agent is not sure which tool category fits the task:

ae recommend [--limit <1-50>] -- "<task>"
recommend -> execute

Recommend sends limit: 5 by default. An agent may place --limit <1-50> before the -- separator to request a different candidate count; for example, ae recommend --limit 8 -- "<task>". The -- separator keeps option-like text such as --json, --help, or --limit inside the task query instead of treating it as a CLI flag. Successful recommend, list, and detail output preserves the backend JSON fields. Select a tool, read its input_schema, and put the complete tool_url and params object in one file:

{
  "tool_url": "https://agentearth.ai/agent-api/v1/tool/execute?recommend_id=...&tool_name=...",
  "params": { "city": "Beijing" }
}

ae execute --request request.json

Recommend results normally include input_schema, so they can go directly to execute. List results do not include input_schema; extract tool_name from the selected tool_url query, run ae detail <tool_name>, then execute the complete tool_url returned by detail. The legacy two-argument execute form remains compatible, but --request is the documented cross-shell path because it keeps & and @ out of shell argument parsing. The CLI uses the fixed https://agentearth.ai origin for business and telemetry requests. Execute accepts only URLs at the configured origin and /agent-api/v1/tool/execute path, rejects URL credentials, fragments, and URLs over 8 KiB before reading the environment credential, and credential-bearing requests never follow HTTP redirects.

List query JSON, execute request files, and legacy execute params JSON are limited to 1 MiB of UTF-8 data.

Every local ae list query failure returns one usage_error recovery shape. Create query.json as one first-level object containing only string, number, or boolean values, for example {"page":1,"page_size":20}, then run ae list @query.json; in PowerShell use ae.cmd list '@query.json'.

The CLI does not rebuild or cache execution URLs:

recommend/list/detail: return the successful backend JSON structure unchanged
execute: POST {"params": ...} to the selected complete tool_url and return the backend JSON unchanged

Output Contract

Core commands default to JSON. Success is written to stdout, failure is written to stderr.

Success and failure are determined by exit code:

exit code = 0: success
exit code != 0: failure

Failure JSON is stable:

{
  "error": {
    "code": "params_invalid",
    "message": "Params must be valid JSON.",
    "hint": "Write valid JSON to request.json or params.json and retry.",
    "retryable": false,
    "action": "fix_params_json",
    "reason": "invalid_json",
    "command": "ae execute --request request.json"
  }
}

Agents should branch on error.action, error.retryable, optional error.reason, and optional error.command instead of parsing prose. Exit code 2 means a local command, file, JSON, or size error; authentication, network, remote, and internal failures use exit code 1. For usage_error, treat error.command as a recovery template and replace placeholders with real task values before retrying; retryable: false means not to repeat the unchanged invalid command.

Execute does not automatically retry business requests. When an execute response could have been lost after the external action started, the CLI returns reason: "outcome_unknown", retryable: false, and action: "verify_outcome_before_retry". The agent must verify whether the action occurred before issuing another execute request.

When AgentAPI returns error_no != 0, the failure object also contains error.error_msg with the backend text unchanged. Agents should read that field for the concrete failure reason and recovery instruction while continuing to use code, action, and retryable for stable control flow. The same backend text is recorded as evt_msg on both the api_request event and the final cli_cmd event.

Successful tool results are returned in full. The CLI does not truncate result based on size.

Command telemetry is timestamped in UTC by the CLI and handed to a detached Node process over stdin after the main result is written. The worker splits final UTF-8 JSON bodies at 7 MiB, waits at most 2 seconds per request, and immediately retries HTTP 408, 5xx, network failures, or client timeouts at most twice. HTTP 429 is not retried; all upload state remains in memory.

See docs/核心功能.md for the command, stdout/stderr, and error contracts.

Development

npm install
npm run typecheck
npm run build
npm test
node bin/ae.mjs --help

Package name is set to @agentearth.ai/cli for publishing.

Documentation

Project documentation lives in docs/.