xapi-to

Agent-friendly command-line interface for xAPI — discover and call capabilities and APIs from your terminal or AI agent.

Installation

# Via npx (no install needed)
npx xapi-to --help

# Or install globally with npm
npm install -g xapi-to

# Or from source
cd xapi-cli && bun install

The published CLI runs on Node.js 18+. Bun is only required for local source development and tests.

Teach Your Agent the xAPI Skill

Paste into Cursor, Claude Code, or any agent that supports skills:

npx skills add xapi-labs/xapi-cli

This installs the bundled xapi skill, which teaches the agent how to call social, search, domains/DNS, crypto, BlockPI RPC, Binance Web3, and AI services through this CLI. Then just ask — "what's the price of BTC" — and it takes it from there. Set up a key first; see Quick Start.

Providers can install the CLI-native xapi-provider skill, which covers service registration, billing and WebSocket configuration, revision publishing, observability, earnings, and linked usage Skills:

npx skills add xapi-labs/xapi-cli --skill xapi-provider

Workers projects can also install the standalone xapi-workers skill, covering deployment, all six managed resource types, complete consumption queries and cleanup:

npx skills add xapi-labs/xapi-cli --skill xapi-workers

Quick Start

# 1. Register a new account (apiKey saved automatically)
xapi-to register
# Open the returned private bindUrl to upgrade the virtual account through Twitter OAuth

# 1b. Or register with an inviter's referral code (please replace xapito to your referral code)
xapi-to register --referral-code xapito

# 2. Or set an existing key without putting it in shell history
read -rsp 'xAPI key: ' XAPI_KEY_INPUT
printf '\n'
printf '%s\n' "$XAPI_KEY_INPUT" | xapi-to config set apiKey=-
unset XAPI_KEY_INPUT

# 3. Or via env var
export XAPI_KEY=sk-xxx
# XAPI_API_KEY is also accepted; XAPI_KEY has higher precedence

# 4. Verify connectivity
xapi-to config health

Usage

xapi-to <command> [args] [flags]

Action Commands

Unified interface for capabilities (built-in) and APIs (third-party). Use --source capability|api to filter.

xapi-to list                                            # list all actions
xapi-to list --source capability                        # only built-in capabilities
xapi-to list --source api --category DeFi               # filter by source and category
xapi-to list --page 2 --page-size 20                    # pagination
xapi-to list --service-id <id>                          # filter by service

xapi-to search "twitter"                                # search by keyword
xapi-to search "token price" --source api               # search APIs only
xapi-to search "token price" --sort relevance           # strongest text match
xapi-to search "token price" --sort price               # lowest comparable price
xapi-to search "twitter" --include-all-versions          # include active non-default majors

xapi-to categories                                      # list all categories
xapi-to categories --source capability                  # categories for capabilities only

xapi-to services                                        # list all services
xapi-to services --category Social --page-size 10       # filter and paginate

xapi-to get twitter.tweet_detail                        # get action schema
xapi-to get-batch twitter.tweet_detail crypto.token.price # get several schemas
xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'  # execute
xapi-to call serper.search --input '{"body":[{"q":"OpenAI"},{"q":"Cloudflare"}]}' # Serper mini-batch
xapi-to call ai.text.chat.fast --input '{"messages":[{"role":"user","content":"Hi"}]}' --stream

Direct serper.* actions use a nested body. Eleven current v7 actions accept one request object or a mini-batch array; serper.reviews accepts only one object. See the bundled Serper guide for the Action list, examples, and dynamic per-credit billing.

Search uses --sort default|relevance|price. default is the recommended order: it considers keyword coverage and match quality first, then favors stable built-in capabilities when matches are otherwise comparable. relevance is source-neutral and selects the strongest text match. price preserves keyword coverage and an exact action ID first, keeps endpoint-local matches ahead of service-only matches, then orders comparable fixed per-call USD list prices from low to high. Dynamic, per-token, per-resource, and unknown prices appear after comparable prices in the same match bucket and are never treated as free. All three modes rank the full matching result set before applying --page and --page-size.

--stream forwards an HTTP Server-Sent Events (SSE) response; it is not a WebSocket client. Active SSE and raw downloads may run longer than 60 seconds, but abort after 60 seconds without data by default. Set XAPI_TRANSFER_IDLE_TIMEOUT_MS to change that idle timeout.

GPT Live is a WebSocket protocol and cannot be invoked with xapi-to call. Read the WebSocket Gateway guide and use a real WebSocket client. The packaged examples/openai-gpt-live-text.mjs demonstrates session.start, managed Responses delegation, text events, and a graceful session.close without placing an xAPI key in source or CLI arguments.

Async Task Commands

Task helpers built on top of the task.poll capability.

xapi-to task poll 550e8400-e29b-41d4-a716-446655440000                 # poll once
xapi-to task wait 550e8400-e29b-41d4-a716-446655440000                 # wait until terminal status
xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 1s --timeout 10m

Provider: Import → Configure → Submit → Wait

provider manages APIs owned by your account. It uses XAPI_API_HOST (default api.xapi.to) and the same saved or environment API key as other commands. In the xAPI Console API Keys settings, grant service:create, service:read, service:update, and service:publish. Legacy allowRegister only grants creation, not the remaining lifecycle permissions. Missing permissions return a nonzero exit with the required scope.

Start from examples/provider/openapi.json, replace its upstream URL, service details, and endpoint contract, then run:

# Inspect current rules; no API key required
xapi-to provider spec-rules --format pretty

# Import a raw OpenAPI 3.0.3 JSON object (not a {openApiSpec: ...} envelope)
xapi-to provider import --file openapi.json > imported.json

# Use the serviceId and revisionId from imported.json (jq is optional)
PROVIDER_SERVICE_ID=$(jq -er '.serviceId' imported.json)
PROVIDER_REVISION_ID=$(jq -er '.revisionId' imported.json)

# Save version configuration to move the draft revision to SANDBOX.
# config.json can be {"description":"Initial release"} when the imported
# endpoints, authentication, and pricing are already complete.
xapi-to provider update "$PROVIDER_SERVICE_ID" \
  --revision "$PROVIDER_REVISION_ID" --file config.json

# Submit the specified revision, then wait for the actual publication result
xapi-to provider submit "$PROVIDER_SERVICE_ID" \
  --revision "$PROVIDER_REVISION_ID" --changelog "Initial release"
xapi-to provider wait "$PROVIDER_SERVICE_ID" \
  --revision "$PROVIDER_REVISION_ID" --interval 2s --timeout 10m

# Inspect owned services, configuration, version overview, or review reports
xapi-to provider list --format table
xapi-to provider get "$PROVIDER_SERVICE_ID" --format pretty
xapi-to provider versions "$PROVIDER_SERVICE_ID" --format pretty
xapi-to provider review "$PROVIDER_SERVICE_ID" --revision "$PROVIDER_REVISION_ID"

When scripting these steps, stop on nonzero exit (for example, use set -e). Import returns the backend validation/preview plus serviceId, revisionId, and state. An HTTP 201 with success: false is a validation failure and exits nonzero; its structured validation errors are preserved. Registration creates a new service each time. If a response is lost, inspect provider list before retrying to avoid duplicate services.

For an authenticated upstream, store credentials in a local JSON object such as {"Authorization":"Bearer YOUR_UPSTREAM_KEY"} and pass --private-headers-file private-headers.json to provider import. Keep this file out of version control. --file - and --private-headers-file - accept stdin, but only one input can consume stdin per command. Files must be JSON; YAML and URL imports are not supported in this command group.

provider update --revision <id> reads a version configuration object, using the backend fields description, baseUrl, baseUrls, authType, privateHeaders, authConfig, openApiSpec, endpoints, and status. Prefer structured privateHeaders for upstream credentials. Endpoint fields include billing configuration such as billingType and costPerCall. Update does not accept a raw OpenAPI document; the nested backend field is openApiSpec: {spec: ...}. Saving that field alone does not re-import endpoint definitions; configure endpoints explicitly when changing the contract.

--mode merge (default) sends PATCH and preserves omitted fields/endpoints. Existing endpoint edits require id, e.g. {"endpoints":[{"id":"ENDPOINT_ID","costPerCall":"0.002"}]}.
--allow-new-endpoints explicitly permits ID-less merge entries to create endpoints. Repeating such a merge can create duplicates.
--mode replace sends PUT. If endpoints is provided, it replaces the endpoint list; include every endpoint you intend to keep. Omitted fields otherwise follow backend PUT semantics. Use full configuration for replacement.

get retains its existing service response; --version v1.0 selects the configuration returned by the backend. Find endpoint IDs in currentVersion.endpoints; provider versions returns working revision IDs in majors[].working.id. For an already-published API, use the existing provider revision start <service-id> <major> command to create a working revision. provider update without --revision continues to update service metadata and rate limits. Existing version update, publish, and positional review commands remain available. The submit and review --revision forms are additional onboarding commands.

Updates to IN_REVIEW, PUBLISHED, or SUSPENDED revisions return a conflict; the backend enforces this check under a transaction lock. When updating privateHeaders, send the complete desired map: it replaces the old map and rebuilds the derived authentication configuration. An empty map without an explicit authConfig clears those credentials. Omitting both fields preserves them.

submit returns {serviceId, revisionId, submission}. A successful submission does not guarantee publication. wait checks the requested revision, succeeds only for PUBLISHED, and outputs the review report with success and reason. --changelog is limited to 2,000 characters by both the CLI and backend. Rejection, a draft/sandbox/suspended revision, or a legacy manual-review hold exit nonzero. Pending review continues until publication, the timeout (default 10 minutes), or optional --max-attempts. Timeout and attempt-limit results include the last received report; polling can be resumed with the same IDs. The deadline also bounds in-flight HTTP requests and retry delays.

Reads retry transient errors; writes are never automatically retried. The CLI redacts credential fields and known credential values from provider output. Redacted reads are for inspection and must not be submitted unchanged as configuration. After an ambiguous write failure, use list, get, or review to inspect the result before repeating the operation. No npm release is implied by a local source checkout; use bun run src/index.ts provider ... or build and run node dist/index.js provider ... while testing unreleased changes.

Sandbox Commands

Sandbox commands provide an AI-friendly cloud computer lifecycle. The fastest safe path is sandbox run: it quotes by capabilities, applies a default $0.20/hour ceiling, creates an instance, waits for RUNNING, executes the command, and terminates in finally even when execution fails.

# One-shot execution with automatic cleanup
xapi-to sandbox run --command 'python3 -c "print(6 * 7)"'

# Arguments after a bare -- are joined as the remote command
xapi-to sandbox run -- node --version

# Pin a provider and request specific capabilities/resources
xapi-to sandbox run \
  --provider cf-edge \
  --capabilities exec,files,ports \
  --cpu 1 --memory 1 \
  --command 'pwd'

# Inspect selection before spending anything
xapi-to sandbox offerings --format table
xapi-to sandbox quote --capabilities exec,files --max-hourly-usd 0.10

# Every command has focused help
xapi-to sandbox create --help
xapi-to sandbox run --help

# Fine-grained lifecycle for agents that need several tool calls
xapi-to sandbox create --capabilities exec,files --wait
xapi-to sandbox exec <id> --command 'npm test' --timeout 120
xapi-to sandbox file write <id> task.md --file ./task.md
xapi-to sandbox file read <id> result.json --output ./result.json
xapi-to sandbox file list <id> --path . --depth 3
xapi-to sandbox port <id> 8080
xapi-to sandbox extension <id> runpod.connection_info --input '{}'
xapi-to sandbox audit <id> --kind operations
xapi-to sandbox history --state HISTORY --page-size 20
xapi-to sandbox suspend <id>
xapi-to sandbox resume <id>
xapi-to sandbox terminate <id>

For a long-running Web server, select an Offering that explicitly declares backgroundExec and ports, then use the provider-managed background mode:

# Confirm the selected row reports background=yes and ports=yes before creating.
xapi-to sandbox offerings --provider daytona --format table

xapi-to sandbox create \
  --provider daytona \
  --capabilities exec,backgroundExec,ports \
  --wait

xapi-to sandbox exec <id> --provider daytona --background --command \
  'python3 -m http.server 25319 --bind 0.0.0.0'
xapi-to sandbox port <id> 25319 --provider daytona

Do not substitute nohup ... & on providers that do not declare backgroundExec: some providers reclaim the command session and its child processes as soon as the foreground exec response completes. A successful background response means the session was accepted; verify the public URL and expected marker before reporting success.

--format table is a compact comparison view; truncated cells end with …. Use the default JSON output when copying a complete quote ID, instance ID, or audit payload. Sandbox subcommands reject unknown flags before making a request.

An exact --offering-id cannot be combined with --max-hourly-usd, because an Offering bypasses requirements-based quote selection. Use requirements plus the ceiling, or create from a quote whose price was already checked. Successful create output includes clientIdempotencyKey. If create --wait fails after the instance was accepted, its structured error includes the instance ID, observed state, idempotency key, and inspect/terminate recovery commands.

Provider pinning uses a provider-specific gateway such as cf-edge.sandbox.xapi.to; the CLI also resolves the deployed production aliases daytona-sandbox.sandbox.xapi.to and e2b-sandbox.sandbox.xapi.to, while the test gateways remain daytona.sandbox.test.xapi.to and e2b.sandbox.test.xapi.to. Omit --provider or use auto for cross-provider selection. sandbox run --keep is deliberately explicit because the instance continues billing until later termination. Remote non-zero command exit codes are returned as the CLI process exit code after cleanup.

For the test service, override only the Sandbox host; the CLI still refuses to send the key outside *.xapi.to or localhost:

XAPI_SANDBOX_HOST=sandbox.test.xapi.to \
  xapi-to sandbox run --provider cf-edge --command 'echo test-ok'

The repository includes a real acceptance suite for the original nine Sandbox Playground workflows. It exercises catalog/quote, AI coding, CI repair, data analysis, parallel agents, GPU connection data, one-shot execution, Cloudflare web preview, suspend/resume, audits, billing, history, and a final zero-active- instance cleanup gate:

# Uses the API key already stored by `xapi-to config set apiKey=-`
npm run test:sandbox:playground -- --host sandbox.test.xapi.to

# Focused retry or lower-cost run
npm run test:sandbox:playground -- --host sandbox.test.xapi.to --only 8,9
npm run test:sandbox:playground -- --host sandbox.test.xapi.to --skip-gpu

Each run writes a redacted JSON report under the operating system temporary directory. The key is read from normal CLI configuration or environment and is never accepted on the command line or written to the report.

The tenth Playground scenario uses the official OpenAI Agents SDK SandboxAgent with DeepSeek through the OpenAI Chat Completions-compatible https://ai.xapi.to/v1 gateway and xAPI Sandbox compute. The reusable adapter is exported as xapi-to/openai-sandbox; its current verified scope is an empty Manifest plus the SDK Shell capability. Run the real SDK agent loop against the test service with:

XAPI_SANDBOX_KEY='sk-sandbox-test-...' \
XAPI_AI_KEY='sk-ai-production-...' \
npm run test:sandbox:openai -- \
  --host sandbox.test.xapi.to \
  --provider daytona \
  --model deepseek-v4-pro

The test keeps credentials separate: XAPI_AI_KEY is sent only to ai.xapi.to, while XAPI_SANDBOX_KEY is sent only to the selected Sandbox Gateway. A production key with both permissions may be supplied to both variables. The test disables OpenAI tracing because an xAPI credential is not an OpenAI telemetry credential, and configures useResponses: false because ai.xapi.to currently exposes the Chat Completions protocol.

For a shorter, zero-context walkthrough of all three public entry points, run the standalone JavaScript demo. It creates its own instances and cleans each one up; no quote ID or instance ID needs to be prepared:

# Required for the default test host; paste without putting the key on argv.
read -s XAPI_SANDBOX_KEY && export XAPI_SANDBOX_KEY

# Required by the OpenAI/DeepSeek section; this targets production ai.xapi.to.
read -s XAPI_AI_KEY && export XAPI_AI_KEY

# Direct HTTP API + local CLI + OpenAI Agents SDK/DeepSeek
npm run demo:sandbox

# Run only one section
npm run demo:sandbox -- api
npm run demo:sandbox -- cli
npm run demo:sandbox -- openai

unset XAPI_SANDBOX_KEY XAPI_AI_KEY

The default test host uses a dedicated Sandbox credential. The OpenAI section uses a separate production AI Gateway credential because there is currently no test AI Gateway. The report includes credential source names but no credential fragments; the CLI child receives only the Sandbox credential. The demo defaults to Daytona and deepseek-v4-pro. Its final JSON verifies markers, TERMINATED, successful operations, settled usage and billing, service-calculated costs, and a zero-residual gate scoped to instances created by that demo (unrelated account instances do not fail it).

Before the package version containing xapi-to/openai-sandbox is published, run the same flow directly from this checkout. The example imports the adapter from src/, defaults to sandbox.test.xapi.to, supports separate Sandbox and AI Gateway credentials, and always closes the created session:

npm run example:sandbox:openai

# Mixed-environment credentials and optional overrides
XAPI_SANDBOX_KEY='sk-sandbox-test-...' \
XAPI_AI_KEY='sk-ai-production-...' \
XAPI_SANDBOX_HOST=sandbox.test.xapi.to \
XAPI_SANDBOX_PROVIDER=daytona \
XAPI_MODEL=deepseek-v4-pro \
npm run example:sandbox:openai

Hosted Workers Commands

Inspect delayed storage collection separately from the financial ledger:

xapi-to workers metering <worker-id> --env preview
xapi-to workers metering <worker-id> --env preview --json

Human output lists each resource's UTC collection window, source status, sample count, last sample and retry times. Missing samples are not zero usage; observed samples are not final settlement. An empty or truncated list does not prove complete history. This source read is independent of the billing snapshot.

workers manages continuously addressable JavaScript applications on xAPI-hosted Cloudflare Workers for Platforms. It is separate from sandbox: use Sandbox for arbitrary shell/build/GPU work, and Workers for HTTP, WebSocket, Webhook, Cron, and persistent Agent entrypoints.

# New project: build, create/update resources, deploy preview, then promote the
# exact tested Artifact to production.
xapi workers templates
xapi workers init my-agent --template persistent-agent
cd my-agent
# Review the plan before resources are created.
xapi workers plan --env preview
xapi workers push --env preview
xapi workers promote --to production

# Existing Cloudflare Worker: Wrangler remains the source of runtime config.
cd existing-worker
xapi workers init --from-wrangler ./wrangler.jsonc
xapi workers plan --env preview
xapi workers push --env preview

# Code rollback never rolls back KV/D1/R2/DO/Queue/Workflow data or Secrets.
xapi workers rollback --env production --to previous

# Follow Tail Worker logs and correlate one request or deployment.
xapi workers logs <worker-id> --env production --tail --since 10m
xapi workers logs <worker-id> --env production --request-id <request-id>

workers push and workers promote keep resource creation/binding and Queue/Cron AFTER_CODE, but do not read or execute D1 SQL. Migrations are explicit:

# Local plan only: no backend call or build; remoteStatus: NOT_CHECKED.
xapi workers d1 migrations plan --binding DB --env preview
# Remote SQL only: requires a linked workerId and an ACTIVE D1 binding.
xapi workers d1 migrations apply --binding DB --env preview

Both commands accept --config PATH and --env preview|production. Apply does not create resources or publish code. Ordinary publishing needs no migration-ledger repair; code rollback does not undo SQL. See the complete migration workflow for first-deployment ordering, receipts, and failure handling.

Choose init based on the starting point:

Starting point	Command
New Worker	`xapi workers init my-agent --template persistent-agent`
Existing React, Vite, Vue, or static Next.js package	`cd app && xapi workers init`
Existing Worker with Wrangler	`xapi workers init --from-wrangler ./wrangler.jsonc`
Next.js SSR	Initialize vinext first, then import its generated Wrangler config

Existing browser applications can be initialized in place. Detection reads package.json and preserves the application's existing dev, build, and test scripts:

cd existing-web-app
xapi workers init
# Run the existing package-manager install command printed by init.
# plan and push run the configured existing build.
xapi workers plan --env preview
xapi workers push --env preview

The initializer preserves package.json, dependencies, scripts and lockfiles. It adds a dependency-free xapi-worker/index.mjs, wrangler.jsonc, and xapi.worker.json. It does not add xapi:build or other package scripts; use the existing development command. There is no separate xAPI local runtime. For workspace packages, init walks to the repository root and honors its declared packageManager or lockfile; the printed install and build commands are therefore safe for Yarn and pnpm monorepos as well as npm and Bun projects. Use --framework react|vite|vue|next only when automatic package detection is ambiguous. init is a one-time adapter setup, not a synchronization command; after it creates xapi.worker.json, use resource commands and plan to manage state.

Next.js with output: 'export' is treated as static assets. SSR Next.js must first create a Workers-compatible bundle with vinext (npx vinext check, then npx vinext init) and import its generated Wrangler configuration. The CLI refuses to misclassify an SSR application as a static SPA.

Web projects can declare their browser build separately from Worker modules. The CLI preserves supported Wrangler assets settings and uploads the files through xAPI as Cloudflare native static assets:

{
  "assets": {
    "directory": "dist/client",
    "binding": "ASSETS",
    "notFoundHandling": "single-page-application",
    "runWorkerFirst": ["/api/*"]
  }
}

workers plan shows whether the selected environment has a dedicated hostname. When webAppReady is false, production promotion asks you to review the base path, root-relative routes, and OAuth callbacks without blocking applications that deliberately support path-prefix hosting. Project bundles use one authenticated multipart request: modules and static assets are not uploaded as independent deployments. Limits are 64 MiB aggregate module content (no arbitrary 200-module cutoff), 100,000 assets / 25 MiB per asset, and 100 MiB total decoded project content. These are CLI validation limits; the platform and provider also validate uploads.

Environment placement is declared beside the budget. Workers remain globally deployed; the data location is inherited only by newly created D1/R2 resources, and Smart Placement lets Cloudflare optimize execution near backends:

{
  "dailyBudgetUsd": 0.25,
  "defaultResourceLocation": "apac",
  "placementMode": "smart"
}

Use xapi workers environment <worker-id> preview --data-location apac --placement smart for an already linked project. This changes the environment default and deployment metadata; it does not move existing D1/R2 data.

Templates are versioned packages shipped with the CLI, not remote code fetched during init. persistent-agent includes buildable source plus KV, D1, R2, Durable Object, Queue, and Workflow declarations. push provisions the environment-specific resources and returns their binding state; secret values remain a separate operation:

export APP_TOKEN='replace-with-an-incoming-request-token'
export MODEL_KEY='replace-with-an-ai.xapi.to-key'
xapi workers secrets set <worker-id> APP_TOKEN --env preview --from-env APP_TOKEN
xapi workers secrets set <worker-id> MODEL_KEY --env preview --from-env MODEL_KEY

The project workflow works without Git. xapi.worker.json may be committed, but Secret values must stay in environment variables or the encrypted Secret store. push never silently deletes extra stateful resources or Secrets.

Public variables travel with the immutable Artifact. By default, deployment replaces public vars: omitted plain_text and json bindings are removed. Top-level Wrangler keep_vars: true retains omitted bindings of both types; false or absence uses replacement. env.<name>.keep_vars is ignored with an import warning and never overrides the root setting. Named environments have their own vars, without inheriting root vars. Native keep_bindings preserves the exact public types requested, so retaining only json does not retain plain_text. A native JSON-string binding stays json. Secrets are independent and always kept across code deployment, regardless of public-variable retention.

workers plan shows public-variable SET, RETAIN, REMOVE, and REPLACE decisions using live target Cloudflare binding names/types, never values. These reads happen during management, not application requests. SET applies the Artifact value; it does not claim that the old value differs. Promotion derives variable intent from the selected immutable preview Artifact and compares it with production; local preview files and local production vars do not rewrite that Artifact.

Roll out the matching backend before upgrading the CLI. It must support keepBindings/varTypes and these authenticated reads:

GET /api/v1/workers/:id/environments/:environment/variables
GET /api/v1/workers/:id/artifacts/:artifactId/variable-configuration

Missing endpoints, failed reads, and malformed responses stop preflight; they must never be treated as an empty variable set. Local tests and dry-run bundles do not establish cloud verification. See the deployment reference for retention and review details.

For project-managed resources, xapi.worker.json is the Git-tracked desired state and xAPI is live state. workers plan always fetches live state; the CLI keeps no third cached copy.

Intent	Project command	Effect
Declare a new resource	`resources add`	Adds desired state only.
Adjust an existing declaration	`resources update`	Replaces the complete declaration locally; `plan` decides whether live state can follow.
Adopt live-only resources	`resources pull`	Reads live state and merges portable fields locally.
Stop declaring a resource	`resources remove`	Removes desired state only; the live resource remains billable.
Delete resource data	`resources destroy --yes`	Removes the one-environment declaration and requests live deletion.
Reconcile	`workers plan`	Reads and compares current live state without mutation.

Add desired resources before applying them:

xapi workers resources add --env both --type kv --binding CACHE
xapi workers resources add --env both --type d1 --binding DB \
  --location apac --read-replication auto
xapi workers resources add --env both --type r2 --binding FILES --location apac
xapi workers resources add --env both --type do --binding ROOM --class-name Room
xapi workers resources add --env both --type queue --binding JOBS
xapi workers resources add --env both --type workflow --binding PIPELINE

# Replace the complete desired declaration before it has been provisioned.
xapi workers resources update --env preview --type d1 --binding DB \
  --location weur --read-replication disabled

xapi workers plan --env preview
xapi workers push --env preview

resources add changes only xapi.worker.json; plan shows the resulting provider operations and push applies them. Repeating an identical add is a no-op, while reusing a binding for another type is rejected. --env both declares the same binding independently for preview and production; it does not make both environments share one physical resource.

Resource and static-assets binding names are case-sensitive: Chat, CHAT, and chat remain distinct. They must match ^[A-Za-z][A-Za-z0-9_]{0,63}$; import, resource editing, and deployment preserve the spelling. This is a bounded native identifier subset, not full JavaScript identifier support. Secret names retain ^[A-Z][A-Z0-9_]{0,63}$ and their existing value-management behavior.

push creates missing preview resources only after its full plan passes. promote performs the same production preflight and, after confirmation, creates missing production declarations before activating the exact tested preview Artifact. A budget mismatch, missing required Secret or incompatible binding blocks activation. An undeclared production resource is retained and unbound by the next deployment. If creation requires an accepted freeze quote, pass its exact version with --retention-price-version.

resources update requires the resource type because it replaces the complete portable declaration. Before the project is linked, it can correct any local declaration. After linking, it rejects type and Durable Object class changes. Changing a live location or D1 replication mode is reported as BLOCKED: the current xAPI API has no in-place resource update, so create a new binding, migrate data, and switch the application explicitly.

Adopt supported live resources that are missing locally with an explicit pull:

xapi workers plan --env preview
xapi workers resources pull --env preview
git diff -- xapi.worker.json
xapi workers plan --env preview

pull imports compatible live declarations initially, then uses a metadata-only .xapi/resource-sync-* baseline for a three-way merge. Local edits and removed bindings are preserved; remote-only changes are adopted; conflicting edits abort without overwriting JSON. It changes no native resources and copies no Secret values. --env both uses independent environment baselines.

Use resources remove --env ... --binding ... only when the live resource must remain. plan explains that the next deployment removes its binding only. To delete data, back it up first and run:

xapi workers resources destroy --env preview --binding FILES --yes

destroy accepts one environment at a time, removes the local declaration before requesting deletion, and reports deletion as requested until the live resource disappears. If the request fails, the live resource remains visible and the user can inspect and explicitly retry deletion. resources list/create/delete <worker-id> ... remain low-level recovery primitives and do not update project files.

Deployment identity includes the code Artifact, remote resource identities, environment bindings and compatibility settings. Secret values are independent and do not trigger a code deployment. Changing only resources or compatibility settings therefore deploys again; repeating an unchanged push reuses the current activation. Older deployments without this configuration fingerprint require one deployment to establish the baseline.

Removing a resource from xapi.worker.json does not destroy it: plan shows the unbinding consequence, and the resource remains billable. resources destroy is the project-aware destructive operation. Preserve a backup before using it and wait until resources list no longer returns the binding. A successful deployment alone is not proof of deletion or final billing settlement.

In CI, set XAPI_KEY and XAPI_API_HOST explicitly, use a Key restricted to the target Worker, and pass --non-interactive; safety preflights are still enforced:

export XAPI_API_HOST=test.xapi.to
export XAPI_KEY="$CI_XAPI_KEY"
xapi workers plan --env preview --format json
xapi workers push --env preview --non-interactive
xapi workers promote --to production --non-interactive

The lower-level commands remain available for diagnosis and custom automation:

# API keys need workers:read / workers:write scopes.
xapi-to workers provider-status
xapi-to workers capabilities --format table
xapi-to workers bindings --format table

# Both environment budgets are explicit ($0.10-$100/day).
xapi-to workers create \
  --name "Daily research agent" \
  --slug daily-research-agent \
  --template agent \
  --preview-budget 0.25 \
  --production-budget 2

# Upload one bundled ES module, or use --file dist/ --main worker.js for code splitting.
xapi-to workers upload <worker-id> \
  --file dist/worker.mjs \
  --idempotency-key artifact-v1

xapi-to workers deploy <worker-id> \
  --artifact <artifact-id> \
  --env preview \
  --idempotency-key preview-v1

# Secrets are encrypted at rest; prefer reading them from a local env variable.
MODEL_KEY='...' xapi-to workers secrets set <worker-id> MODEL_KEY \
  --env preview --from-env MODEL_KEY
xapi-to workers resources list <worker-id> --env preview --format table
xapi-to workers secrets list <worker-id> --env preview --format table

# Persistent schedules remain Worker-scoped rather than project resource declarations.
# Queue includes an xAPI-managed consumer. Send a local route envelope from
# Worker code; delivery is at least once, so make /tasks/run idempotent:
# await env.TASK_QUEUE.send({
#   path: '/tasks/run', method: 'POST', body: { taskId: 'task_123' }
# });
xapi-to workers schedules create <worker-id> \
  --name heartbeat --cron "*/15 * * * *" --timezone UTC \
  --env preview --path /cron --method POST

# Optional: build source in an ephemeral xAPI Sandbox. A successful result
# contains artifactId, which is deployed exactly like an upload.
xapi-to workers build <worker-id> \
  --project . \
  --entrypoint src/index.ts \
  --command "npm install --ignore-scripts && npm run build" \
  --output dist/worker.mjs \
  --idempotency-key build-v1

xapi-to workers get <worker-id> --format pretty
xapi-to workers audit <worker-id> --format table
xapi-to workers invocations <worker-id> --env production --format table
xapi-to workers logs <worker-id> --env production --format table
xapi-to workers usage <worker-id> --env production --format pretty
xapi-to workers billing-status --format pretty
xapi-to workers domains list <worker-id> --format table
xapi-to workers budget <worker-id> production --daily-usd 3
xapi-to workers delete <worker-id> --yes

Set XAPI_API_HOST=api.test.xapi.to for the test control plane. Mutating requests are not retried automatically; when a deployment result is uncertain, inspect the Worker and retry with the same idempotency key.

For a custom hostname, workers domains attach --xdomain-domain-id automates ownership TXT through xdomain. Without an xdomain record, use the public manual DNS flow (the authoritative zone must still belong to the platform CF account):

xapi-to workers domains challenge <worker-id> --env preview \
  --hostname chat.example.com --format json > challenge.json
# Publish the exact TXT dns.name / dns.value from challenge.json, then:
xapi-to workers domains attach <worker-id> --env preview --challenge-file challenge.json
xapi-to workers domains list <worker-id>

Remove that temporary TXT after attachment is accepted. PROVISIONING is not yet ACTIVE; verify TLS/routing and then the application's business route. See the bundled domain guide for DNS propagation, expiry and explicit retry instructions. No custom domain is required to use a platform-provided public address.

OAuth

Bind third-party OAuth accounts (e.g. Twitter) to your API key.

xapi-to oauth bind --provider twitter                   # bind Twitter account
xapi-to oauth providers                                 # inspect current providers/default scopes
xapi-to oauth bind --provider twitter --scopes "<scope list>" # optional explicit override
xapi-to oauth status                                    # list current bindings
xapi-to oauth unbind <binding-id>                       # remove a binding
xapi-to oauth providers                                 # list available providers

Account

xapi-to register                                        # create account, saves apiKey automatically
xapi-to register --referral-code xapito                 # register with an inviter's referral code (please replace xapito to your referral code)
xapi-to register xapito                                 # positional shorthand for --referral-code
xapi-to register --force                                # replace an existing file-based key
xapi-to balance                                         # show USD balance
xapi-to usage <request-id>                              # finalized cost + balance-after receipt
xapi-to usage wait <request-id> --timeout 1m            # poll until a streaming receipt is finalized
xapi-to earnings                                        # spendable balance + provider earnings
xapi-to earnings list --status SETTLED --limit 20       # provider earning records
xapi-to earnings transfer 1 --idempotency-key reinvest-001 # reinvest settled earnings
xapi-to topup                                           # generate payment URL
xapi-to topup --method stripe --amount 10               # stripe, $10
xapi-to topup --method x402                             # x402 (USDC on Base)

earnings summary/list require the earnings:read scope on the current key; earnings transfer requires earnings:transfer. Transfers are one-way and idempotent: reuse a key only when retrying the same amount.

Provider Management

Provider commands use scoped XAPI-KEY routes for service and release management without a JWT exchange:

xapi-to provider list
xapi-to provider create --file ./service.json
xapi-to provider update <service-id> --about-file ./ABOUT.md --website https://example.com
xapi-to provider update <service-id> --rate-limit-requests 100 --rate-limit-period-seconds 60
xapi-to provider update <service-id> --clear-rate-limit
xapi-to provider versions <service-id>
xapi-to provider revision start <service-id> 1
xapi-to provider version update <service-id> <version-id> --file ./contract.json
xapi-to provider diff <service-id> 1
xapi-to provider publish <service-id> <revision-id> --changelog-file ./CHANGELOG.md
xapi-to provider metrics <service-id> --days 7
xapi-to provider events --after '<opaque-next-cursor>'

Service rate limits are optional and supported only for proxied services. Both numeric flags are required when setting a limit; the quota is shared by all API keys belonging to the same user for that service.

Service usage tutorials are Skill packages. Scaffold one from the serving contract, submit it for review, wait for publication, then link it:

xapi-to provider skill scaffold <service-id> --output ./my-skill/SKILL.md
xapi-to skill submit --dir ./my-skill
xapi-to skill wait <submission-id> --timeout 10m
xapi-to provider skill link <service-id> <skill-id>
xapi-to provider skill fingerprint <service-id> --skill-version-id <version-id>

Run xapi-to provider --help and xapi-to skill --help for the complete lifecycle, rollback, deletion, GitHub import, scope, and safety options.

Config

xapi-to config show                                     # show current config
xapi-to config set apiKey=-                             # paste key, then press Ctrl-D
xapi-to config health                                   # check backend connectivity

XAPI_KEY overrides XAPI_API_KEY, and both override the config file. The CLI warns when a saved key is shadowed. Unset the environment variable before register, including register --force, so the new account key becomes active.

Workflow: Always GET before CALL

Before calling any action, always read its schema first to understand required parameters:

# 1. Find the action
xapi-to search "twitter"

# 2. Read its schema
xapi-to get twitter.tweet_detail

# 3. Call with correct parameters
xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'

For APIs that return binary data, use --output to request raw bytes and save them directly. The CLI refuses to overwrite an existing file.

xapi-to call openrouter.audio_speech \
  --input '{"body":{"input":"Hello","model":"hexgrad/kokoro-82m","voice":"af_bella"}}' \
  --output speech.mp3

Output Formats

Normal command output is JSON by default. call --stream writes raw HTTP SSE frames, while call --output writes raw response bytes to the requested file.

xapi-to list --format json                              # default, machine-readable
xapi-to list --format pretty                            # pretty-printed JSON
xapi-to list --format table                             # human-readable table

Environment Variables

Variable	Description
`XAPI_KEY`	API key (overrides config file)
`XAPI_API_KEY`	Compatible API key alias (overrides config file; lower priority than `XAPI_KEY`)
`XAPI_SANDBOX_KEY`	Sandbox-only credential for OpenAI SandboxAgent examples/tests
`XAPI_AI_KEY`	AI Gateway credential for OpenAI-compatible model calls
`XAPI_ACTION_HOST`	Action service host (default: `action.xapi.to`)
`XAPI_API_HOST`	Auth/account service host (default: `api.xapi.to`)
`XAPI_SANDBOX_HOST`	Sandbox gateway host (default: `sandbox.xapi.to`)
`XAPI_OUTPUT`	Default output format (`json`\|`pretty`\|`table`)
`XAPI_TRANSFER_IDLE_TIMEOUT_MS`	SSE/download idle timeout in milliseconds (default: `60000`)

Config is stored at ~/.xapi/config.json.

Selected Built-in Capabilities

This is a small quick-reference subset, not the complete or permanently fixed catalog. Use xapi-to list --source capability, search, and get for the current IDs and schemas.

ID	Description
`twitter.tweet_detail`	Get tweet details and replies
`twitter.user_by_screen_name`	Get user profile by username
`twitter.user_tweets`	Get tweets from a user
`twitter.user_tweets_and_replies`	Get tweets and replies from a user
`twitter.user_media`	Get media posts from a user
`twitter.following`	Get user following list
`twitter.followers`	Get user followers
`twitter.retweeters`	Get tweet retweeters
`twitter.search`	Search tweets
`ai.text.chat.fast`	Fast AI chat completion
`ai.text.chat.reasoning`	Advanced reasoning chat
`ai.text.chat.auto`	Model-selected chat with provider fallback
`ai.text.summarize`	Summarize long text
`ai.text.rewrite`	Rewrite text with different styles
`ai.embedding.generate`	Generate vector embeddings
`web.search`	Web search
`web.search.realtime`	Realtime web search with time filters
`web.search.news`	News search
`crypto.token.price`	Crypto token price and changes
`crypto.token.metadata`	Crypto token metadata

Security

General action commands retain compatibility with xapi.to, *.xapi.to, xapi.xyz, *.xapi.xyz, and localhost/loopback development hosts. Sandbox commands deliberately apply the stricter *.xapi.to/localhost-only policy.
The key is stored at ~/.xapi/config.json; the CLI enforces owner-only Unix permissions — do not expose this file
topup outputs a payment URL containing the API key — do not share publicly

License

MIT

Native framework deployment bundles

Framework output can be exported with Wrangler's deploy --dry-run --outfile dist/app.worker.bundle and published through xapi workers push. The CLI retains native module names/types/bytes and separately publishes static Assets. See the Workers guide for configuration, supported metadata and current transport boundaries.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
docs		docs
examples		examples
schemas		schemas
scripts		scripts
skills		skills
src		src
templates		templates
.gitignore		.gitignore
.release-please-manifest.json		.release-please-manifest.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
package.json		package.json
release-please-config.json		release-please-config.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

xapi-to

Installation

Teach Your Agent the xAPI Skill

Quick Start

Usage

Action Commands

Async Task Commands

Provider: Import → Configure → Submit → Wait

Sandbox Commands

Hosted Workers Commands

OAuth

Account

Provider Management

Config

Workflow: Always GET before CALL

Output Formats

Environment Variables

Selected Built-in Capabilities

Security

License

Native framework deployment bundles

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

xapi-to

Installation

Teach Your Agent the xAPI Skill

Quick Start

Usage

Action Commands

Async Task Commands

Provider: Import → Configure → Submit → Wait

Sandbox Commands

Hosted Workers Commands

OAuth

Account

Provider Management

Config

Workflow: Always GET before CALL

Output Formats

Environment Variables

Selected Built-in Capabilities

Security

License

Native framework deployment bundles

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages