XAgent CLI

XAgent CLI is the local client for the XAgent Developer Public API. It runs on developer machines and CI runners; it is not a second cloud task service.

Component boundary

Local terminal / CI / local Agent
  -> xagent CLI and MCP
  -> HTTPS Developer Public API
  -> test-agent-service
  -> Redis / Go exec / cloud device

This repository owns local commands, Profile and credential handling, local YAML validation, the shared HTTP SDK, machine-readable output, exit codes, MCP adapters, packaging, and release artifacts. It must not import Flask applications, server DAOs, Redis clients, task services, or device-internal protocols.

The server repository D:\Py\test-agent-service owns authentication authority, Developer Token storage, Principal resolution, public API routes, resource authorization, Run orchestration, task dispatch, persistence, and report mapping. The Go executor repository D:\Py\exec owns strict consumption of the agreed queue protocol.

Current source layout

src/                 TypeScript CLI, SDK, MCP, Script and local Draft implementation
tests/               contract, stdio and behavior tests
contracts/           synchronized public contract snapshot
skills/              packaged Skill documents and References

The authoritative public contract is maintained in D:\Py\test-agent-service\contracts\developer\v1. Files under this repository's contracts/ directory are release inputs synchronized from that source; client agents must not change their semantics independently.

The cross-component product and system design documents remain under D:\Py\test-agent-service-dev1.1\docs\xagent-cli; its repository-routing table determines which project each implementation task may modify.

Run scripts

Personal Runs use package_id from YAML or --package-id to select an existing platform APK. Project CI Runs can instead upload the APK built from the current commit and pass the returned temporary ID to run.

xagent run D:\Py\xagent-cli\examples\existing-app-smoke.yaml --device-id DEVICE_ID
xagent run D:\Py\xagent-cli\examples\smoke.yaml --device-id DEVICE_ID
xagent run D:\Py\xagent-cli\examples\smoke.yaml --package-id OTHER_PACKAGE_ID --device-id DEVICE_ID

Project CI flow:

xagent init --base-url https://xagent.example --upload-base-url https://files.example --token-type project_ci --name ci --token-env XAGENT_CI_TOKEN
xagent --json --profile ci apps upload .\app-debug.apk
xagent --json --profile ci --config .\xagent.yaml run .\tests\smoke.yaml --target android-single --app-upload-id APP_UPLOAD_ID --idempotency-key PIPELINE_KEY --wait
xagent --json --profile ci apps release APP_UPLOAD_ID

File-service upload requests default to a 15-minute timeout. Override it when needed with xagent apps upload .\app-debug.apk --upload-timeout 900 or xagent run tests\smoke.yaml --apk .\app-debug.apk --device-id DEVICE_001 --upload-timeout 900.

apps upload and apps release require a newly issued project_ci Token with the app:upload capability. One upload can be bound to one Run. Release is idempotent and should run from CI cleanup (after_script / finally). The Profile's upload_base_url points to the file service. The CLI sends the same Developer Token only to /app/ci/init; chunk requests use a short-lived upload ticket and never persist the Token in project files.

Development

The supported runtime and build path is Node.js 18 or later. No Python runtime, PyInstaller or platform compiler is needed to build the customer package.

Set-Location D:\Py\xagent-cli
npm ci
npm run check
node .\dist\cli.js --json version
node .\dist\cli.js --json validate .\examples\smoke.yaml
npm pack --dry-run

npm run check runs the synchronized contract fixtures, Target hash checks, local Draft persistence tests and a real MCP stdio initialize / tools/list exchange.

npm installation

The customer-facing installation package is the single package @miluan/xagent. It contains the compiled TypeScript CLI, MCP server, synchronized public schemas, Skills and References. It does not download a platform-specific binary package and does not contain Python source.

npm install --global @miluan/xagent
xagent --json version

Agent Host Skill and routing

The npm package is the execution client. Customers also receive one complete external xagent-skill directory that can be imported directly into an Agent Host. It discovers XAgent and routes one request to one isolated MCP domain:

xagent integrations install codex
xagent integrations doctor --host codex
xagent --json integrations options
xagent --json integrations route author --profile personal

The default xagent-local MCP remains action. It is a long-lived stateful device-control process that owns the current device Session, screen evidence, pre-action renewal checks, and graceful-shutdown release. An idle MCP process does not renew a Session in the background. Do not replace it with setup mode. The Skill must tell the user this default and present the behavior choices before any side-effect route is selected.

The route is explicit and one-to-one:

setup   -> mcp --mode setup   -> xagent-cli
action  -> mcp --mode action  -> xagent-explore-device
author  -> mcp --mode author  -> xagent-author-test
run     -> mcp --mode run     -> xagent-run-test
analyze -> mcp --mode analyze -> xagent-analyze-failure
repair  -> mcp --mode repair  -> xagent-repair-test
report  -> mcp --mode report  -> xagent-test-report

The same route is available without Shell through setup MCP's local xagent_workflow_route Tool. Each MCP process exposes one domain only; changing domains requires restarting it with the new explicit --mode. A mode can load only its mapped Skill, and a failed Skill load must stop all device, upload, Authoring, Run, and report side effects.

xagent integrations install writes only XAgent's own Skill files. It does not overwrite an existing Host configuration or write Developer Tokens. The integration package can be prepared for a market or GitLab Release with:

npm run package:integrations

The generated versioned Skill directory and ZIP are under release/ and are intended to be published as static Release assets, not served by a runtime API. The ZIP extracts with SKILL.md at its root. The npm package and the Skill ZIP are separate artifacts: the former executes requests, while the latter is the Agent Host entry and routing contract.

The same package runs on Windows, Linux and macOS on x64 or arm64 with Node.js 20.9 or later. Interactive saved credentials use the operating system credential store through a prebuilt N-API adapter; CI Profiles continue to use explicitly named environment variables. Downstream CI jobs install from npm and are never granted permission to clone this repository.

GitLab runs the TypeScript tests and build once on Linux, then produces the same npm tarball for every supported operating system. Publishing is manual and requires a masked NPM_TOKEN; no Windows Runner is required.

Migration boundaries, Agent Host integration and platform limitations are documented in docs/typescript-migration.md.