VTX Macro CLI

Command-line and MCP access for VTX Macro automation.

Install or update

npm install -g @vtxmacro/cli
vtx --version

The host supports Windows x64 and Linux x64, including WSL. The package installs the exact supported OpenAI Codex runtime and GitHub Copilot SDK. The VTX host verifies the Codex runtime's version and digest before use; it does not borrow a Codex binary from PATH or an editor extension. For Windows-login auto-start, install and configure the CLI from native Windows; a CLI installed only inside WSL cannot start the WSL virtual machine at login. An npm update does not replace code already loaded by a running durable service. After updating, check vtx inference-host service status --json. If the service was already desired-running, run vtx inference-host service stop followed by vtx inference-host service start, then verify status and logs. Leave an intentionally stopped service stopped until you want to run it.

Configure

export VTX_PROFILE_ID="<profile-id>"
vtx auth login --scopes read,bot:control

CLI

vtx --json auth whoami
vtx --json bots status
vtx --profile <profile-id> runtime run --follow

MCP

Configure your MCP-compatible agent app to start:

vtx-mcp

The CLI and MCP server use the same saved token and environment variables.

Agent inference hosts

Both paths use a separate least-privilege insights:inference OAuth grant. VTX never receives an agent vendor password, OAuth token, or subscription credential.

Durable subscription hosts

Codex remains the reference implementation and its existing App Server, authentication, quota, recovery, and provider-mode path are unchanged. GitHub Copilot is an additive preview adapter that uses the official SDK and validates final text against VTX's immutable schema. An uncertain interrupted Copilot call is quarantined as outcome_unknown and is never blindly repeated. A different adapter cannot replace an installed Codex instance; it needs a distinct instance and VTX grant. VTX resolves the package-owned pinned Copilot platform runtime explicitly and rejects an auto-only catalog because it cannot prove the effective model.

An explicitly capable Codex model can also control Main in Agent mode using the same VTX OAuth grant and private Codex login. VTX assigns the running bot but does not send a VTX-authored prompt or set the analysis cadence. Codex keeps a durable Agent thread, chooses when to wake, requests only the assignment-scoped VTX data it needs (or none), and submits the normal structured decision for VTX to validate and execute. Review and Screener remain Provider-only.

Before the first Codex login, enable Device code authorization for Codex in ChatGPT Security settings. Only enter a device code from a login you initiated, and never share it. The automated host reads the authenticated Codex model picker and advertises every visible model with that model's exact display name, default effort, and supported reasoning efforts. Hidden Codex entries are not exposed. Before starting a Trader, confirm that the VTX AI page shows the intended authenticated ChatGPT email and plan. The host reads the live Codex account window: a reached limit pauses new dispatch until its reported reset, while a transient throttle uses a short bounded cooldown. The selected AI model row estimates the open VTX profile's attributable membership burn rate for that subscription, expressed as equivalent percentage points per hour, day, and seven days. Account-wide quota percentages remain in safe host diagnostics instead of the profile-scoped selector.

vtx inference-host login
vtx inference-host codex-login
vtx inference-host doctor --json
vtx inference-host service install
vtx inference-host service status --json
vtx inference-host service logs
vtx inference-host logout
vtx inference-host codex-logout
vtx inference-host revoke

For Copilot, sign in with the official Copilot CLI, then run:

vtx inference-host login --instance copilot-1
vtx inference-host doctor --adapter copilot --instance copilot-1 --json
vtx inference-host service install --adapter copilot --instance copilot-1

To connect another Codex subscription to the same VTX account, repeat the login and service-install commands with a stable local name such as --instance codex-2. Each named instance has an isolated VTX grant, Codex home, credential file, runtime state, recovery state, and worker; one per-user OS supervisor runs all installed instances. Use service status --json to inspect the installed workers. The installer rejects duplicate authenticated ChatGPT emails and fails closed when it cannot prove multiple subscriptions are distinct. Use service uninstall --instance <name> to remove one worker; unqualified service uninstall removes the whole supervisor. The legacy unqualified host commands continue to target default.

On native Windows, if service status or logs show that guarded recovery is blocking one installed subscription, recover that exact instance without rebooting:

vtx inference-host service recover --instance <name> --force-recovery --json

Recovery is intentionally noninteractive and requires both --instance and --force-recovery; --json changes only the output format. The shared supervisor briefly quiesces so every installed worker can stop cooperatively, then VTX restores its previous desired state and the same peer subscriptions. The command never kills an arbitrary process, logs either account out, changes VTX profile settings, or controls a Trader. If any package-owned VTX automation is still live, recovery fails closed and preserves its evidence.

For each VTX profile and lane, Host #1 is tried first and later compatible hosts follow in the saved Host cascade order. Distinct computers may use the same authenticated subscription; provider quota remains account-level. Quota/credits exhaustion can advance only to a later host reporting a different account identity. Unusable authentication and exhausted recoverable host failures can advance the same logical call. VTX never changes provider, model, effort, or response mode, and never cascades a bad request, policy rejection, or uncertain dispatch outcome.

Automated hosts do not impose a subscription-specific profile-count or concurrency limit by default. Set an explicit positive integer with --max-concurrency when you want a local limit. Every active turn shares the live subscription rate-limit gate and cooldown; unlimited local admission does not guarantee capacity beyond the authenticated account's current entitlement. Updating from an older bounded host removes its previous numeric limit; run service install --max-concurrency <positive-integer> only to add one back.

Every durable host uses a separate least-privilege insights:inference OAuth grant. Codex additionally keeps its ChatGPT subscription login in a dedicated private Codex home; Copilot uses its official cached user login. No vendor credential is written to the VTX service manifest. The per-user OS service starts immediately, starts again at login, and reconnects after sleep, network loss, or a worker exit. Stopping a VTX bot leaves the provider online and idle. Use vtx inference-host run only for foreground diagnostics. VTX logout/revoke and Codex logout are intentionally separate operations. JSON foreground and service logs include safe concurrency, latency, token, failure-code, and cooldown events without prompts, responses, or credentials. Use service logs --instance <name> to isolate one subscription.

Use vtx inference-host --help for command discovery. The VTX login verifies that the selected credential store can read back the exact saved grant. If an OS credential store such as Windows Credential Manager cannot retain it, VTX revokes the new remote grant and fails with an actionable error. Retry with the supported private-file store by setting VTX_INFERENCE_HOST_CREDENTIAL_STORE=file before running vtx inference-host login again. In PowerShell use $env:VTX_INFERENCE_HOST_CREDENTIAL_STORE="file"; in bash use export VTX_INFERENCE_HOST_CREDENTIAL_STORE=file.

The browser callback shows a VTX authorization-complete page. If a browser extension instead shows ERR_BLOCKED_BY_CLIENT but the CLI reports logged_in and doctor reports credential-present, only the local confirmation page was blocked; the grant succeeded.

Any compatible agent harness

Codex, Claude Code, Cursor, GitHub Copilot, Antigravity, and other agents that can run shell commands can use their existing first-party session without a VTX-owned vendor adapter:

vtx inference-host login
vtx inference-host agent-connect \
  --adapter <lowercase-harness-id> \
  --model <exact-model-id> \
  --model-label "<display label>" \
  --effort <reasoning-effort> \
  --json
vtx inference-host agent-run
vtx inference-host agent-next --wait-seconds 50 --json

agent-next returns separate exact system_prompt, user_prompt, context_json, and output_schema_json fields. The agent reasons in its own session, then writes one JSON object to agent-complete stdin. At minimum that object contains a result string. If the harness exposes exact token usage, include the published usage object; otherwise VTX records usage as explicitly unavailable. For agent-fail, choose the truthful dispatch state and set retryable true only when a fresh attempt is safe:

{"dispatch_outcome":"not_dispatched","failure_category":"adapter","failure_code":"harness_unavailable","retryable":true}
{"dispatch_outcome":"confirmed_dispatched","failure_category":"adapter","failure_code":"no_reliable_result","retryable":false}
{"dispatch_outcome":"outcome_unknown","failure_category":"transport","failure_code":"dispatch_confirmation_lost","retryable":false}

Use not_dispatched only when no harness inference began, confirmed_dispatched when it began but returned no trustworthy result, and outcome_unknown when dispatch itself cannot be confirmed. Pipe exactly one object to vtx inference-host agent-fail --json.

Claude Code, Antigravity, Gemini CLI, Kiro, Grok Build, Cursor, Amp, Auggie, Junie, Warp/Oz, Qwen Code, and OpenCode remain on the explicit foreground agent loop. Their current subscription routing, effective-model identity, schema, usage, or crash-recovery contracts do not yet meet every durable VTX acceptance fence. The public Insights matrix records the specific limitation instead of treating headless support alone as durability.

Keep agent-run open in a separate terminal and keep calling agent-next while the host should remain available. The independent keeper preserves truthful liveness while the harness reasons. This same loop supports Main, Review, and Screener in Provider mode; and normally running VTX Client Mode or Server Mode bots. Server Mode keeps the normal VTX call fee. Client Mode has no VTX platform fee. Neither mode falls back to another model when the agent host is unavailable.

After any approved Trader start, use vtx --profile <profile-id> bots status to confirm the normal Trader remains running. If it returns to Stopped, use vtx --profile <profile-id> runtime events to read the latest error before one controlled retry. A start receipt or a brief Live label is not proof of a running bot.

Remove

First uninstall any durable service, stop any foreground run or agent-run process, revoke the VTX inference grant, then uninstall the package. Cleanup refuses while a foreground host process still owns the host. Automated Codex users should also remove the dedicated Codex login:

vtx inference-host service stop
vtx inference-host service uninstall
vtx inference-host revoke
# Automated Codex host only:
vtx inference-host codex-logout
npm uninstall -g @vtxmacro/cli

If an older failed login left no local credential to revoke, disconnect that inactive inference grant from Connected Agent Apps on the VTX Insights page before logging in again.