CLI reference

status and deployments: free reads.

status reads the current state of a project, and deployments lists its deployment history. Both are free — they never produce a payment challenge — so they can run as often as a monitor or an agent needs.

Synopsis

$ npx x402-hosting@latest status
$ npx x402-hosting@latest status --json
$ npx x402-hosting@latest deployments --limit 50 --all

Both commands read x402-hosting.json in the current directory to find the project; without that file they refuse to run. A successful status also refreshes the record with the server's latest values.

status

The default output is three lines: the URL and project state, the owner wallet, and the expiry. Project states include AWAITING_ACTIVATION — the upload is paid, the duration payment is not — DEPLOYING, ACTIVE, and EXPIRED, which covers the 30-day grace window in which renewal still works.

https://app-682fe91de571a7338dd1.x402-hosting.com — ACTIVE
Wallet: 0x4f3a…9c21
Expires: 2026-09-24T13:18:13.688Z

With --json, the full status object prints instead, including the project id, slug, activation deadline, renewal deadline, and the current and pending deployment ids — everything a script needs.

deployments

deployments prints one line per deployment: its sequence number, its UUID, its state — DEPLOYING, READY, FAILED, or DELETED — and whether it is the current or pending deployment. Those ids are what rollback takes as its argument.

d3 7b2e…-…-…-…-… READY current
d2 4a91…-…-…-…-… READY
d1 0f6c…-…-…-…-… READY

Flags

  • status --json — machine-readable project state
  • deployments --limit <n> — deployments per page, an integer from 1 through 100; defaults to 20
  • deployments --all — follow the cursor and fetch every page
  • deployments --json — the full deployment objects as JSON

Why free reads matter

Every paid command costs money, so never re-run deploy just to check on things — check status instead. For agents, free reads close the loop: deploy, then poll status until the state is ACTIVE, without spending a cent on supervision. See the docs for the read API behind both commands.

Related guides