Command reference
Every 0x command and flag in @0xlimo/cli 0.1.4, what it calls, what it prints, and its errors.
These are all the commands in @0xlimo/cli 0.1.4 (packages/cli/bin/x1.mjs). [dir] defaults to the current directory. Unless a command says otherwise, it prints its result as JSON on stdout and its progress on stderr, so 0x publish > out.json captures just the result. Errors print x1: <message> on stderr and exit with 1 (exit codes).
#0x init / 0x new
0x init [<template> [dir]] [--list]
0x new [dir] --template <template>Creates a starter game. With no template, or with --list, it lists the templates.
| Argument | Meaning |
|---|---|
<template> | three, phaser, babylon or canvas. The aliases three-js, threejs, babylonjs, babylon-js, vanilla and vanilla-canvas also work. |
dir | Target directory. Default: my-<template>-game. It must be empty or not exist. |
--template <t> | (0x new) The template, when the first argument is the directory |
It writes .gitignore (node_modules/, .x1/), and .npmrc with @0xlimo:registry=… when the CLI came from a registry other than npmjs.org. For three, it copies three.js (three.module.min.js, GLTFLoader, BufferGeometryUtils, LICENSE) into vendor/.
Errors: unknown template "…", <dir> is not empty.
#0x dev
0x dev [dir] [--port 5173] [--no-seed] [--verbose]Serves the game locally the way 0x serves it, at http://localhost:<port>/.
| Flag | Default | Meaning |
|---|---|---|
--port <n> | 5173 | Port to listen on (127.0.0.1) |
--no-seed | seeding on | Don't start the local seeder |
--verbose | off | Print the seeder's log |
It runs:
- a static server with single-range support, serving the 0x runtime files (
x1-sw.js,x1/…) and anx1.json; - a meshtorrent tracker behind
/p2p/; - a seeder of every file in the swarm manifest;
- a development broadcast service at
/x1/bcast/serverand/x1/bcast/player.
The site is staged in <dir>/.x1/site as links to your files plus swarm/. Your folder gets nothing new except .x1/. If 0x.config.json has "dist", that subdirectory is served. The swarm policy is swarm-assets.json, or the default. Stop it with Ctrl-C.
Needs @x1/meshtorrent (installed with the CLI), or ZEROX_MESHTORRENT set to a built checkout.
#0x login, logout, whoami
0x login [--api <url>] [--token <0xpub_...>]
0x logout
0x whoami| Flag | Meaning |
|---|---|
--api <url> | The hosting API. Default: https://api.0x.limo, or the saved one. |
--token <0xpub_…> | Checks and saves an existing publish token instead of the device sign-in |
Without --token, 0x login runs the device sign-in: it prints a URL and a code, waits for your approval, and mints a publish token. See Accounts. 0x logout deletes the saved credentials. 0x whoami prints GET /v1/hosting/me: your account, usage and limits. It fails with not signed in (0x login) when there is no token.
#0x publish
0x publish [dir] [--site <name>] [--api <url>] [--server]Uploads the build to 0x hosting as a new immutable version and prints where it plays. This is resumable: run it again after an interruption and it uploads only what is missing.
| Flag | Meaning |
|---|---|
--site <name> | The site. Default: "site", else "id" in 0x.config.json. |
--api <url> | The hosting API. Default: ZEROX_API, else the saved login, else https://api.0x.limo. |
--server | Also deploys the game's server after the site, the same as 0x deploy-server. It is also on when 0x.config.json has "server": {"deploy": true}. Takes the deploy-server flags. |
Steps:
- Read
0x.config.json. Upload from"dist"(default.). - List the files (skipping what is never uploaded) and hash each one.
- If the site doesn't exist, create it (
POST /v1/hosting/sites). If it belongs to someone else, stop. - Open a version (
POST /v1/hosting/sites/<site>/versions {files, csp}). The service answers with the hashes it lacks. - Upload them, 6 at a time (
PUT /v1/hosting/blobs/<sha256>). Uploads that get429or5xxare retried up to 5 times. - Finalize (
POST …/versions/<n>/finalize): content check, 0x runtime, swarm manifest, site policy.
Progress lines include version N (resumed), warnings, the swarm summary, and the security policy (enforced or report-only, what you declared, and how many inline scripts and styles were hashed). If index.html doesn't load ./x1/boot.js, you get a note that players will get every file from the origin.
stdout:
{
"url": "https://my-game-play.0x.limo/sites/my-game/3/",
"site": "my-game",
"version": 3,
"manifest_sha256": "…",
"universe": { "id": "my-game", "name": "…", "web": { "hosted": "https://my-game-play.0x.limo/sites/my-game/3/", "params": "" }, "…": "…" }
}universe is the launcher catalog entry. You can paste it into the launcher's Developers page to try the game in your own library.
Errors:
not signed in: run \0x login` (or set ZEROX_PUBLISH_TOKEN)`no site name: pass --site <name> or set "id" in 0x.config.jsonthe site name "…" belongs to another developer: pick another with --siteupload refused:followed by one line per problemthe site builder refused this version:followed by the findings- quota and limit errors (see Hosting limits)
#0x publish --to (self-hosting)
0x publish [dir] --to <dir | user@host:path> [--origin <https url>] [--tracker <wss url>] [--policy <file>] [--server]
[--mount <url prefix>=<dir>]... [--mount-exclude <glob>]... [--mount-cache <dir>]Builds the site locally and copies it to a directory, or to user@host:path with rsync -a --delete. Nothing is uploaded to 0x. The build stages a copy, adds the 0x runtime and x1.json, builds and verifies the swarm manifest (swarm/manifest.json, .torrent files, the content-addressed store), and copies the result. stdout is the universe JSON for the launcher.
| Flag | Meaning |
|---|---|
--to <target> | A local directory (replaced) or user@host:path |
--origin <url> | The public https URL the site will be served at (goes into universe). Default: file://<dir>/ for a local target, https://example.invalid/ for a remote one. |
--tracker <wss url> | The tracker the site announces to. Default: the site's own /p2p/tracker. |
--policy <file> | The swarm policy file. Default: swarm-assets.json in the game, else the default policy. |
--mount <prefix>=<dir> | Repeatable. A directory your server serves at that URL prefix goes on the swarm in 1 MiB pieces, hashed in place and never copied into the site. See Mounts. |
--mount-exclude <glob> | Repeatable. Files of every --mount that stay on the origin (case-insensitive, relative to the mount) |
--mount-cache <dir> | Where piece hashes are kept between publishes. Default <dir>/.x1. |
Mounts are not in a published CLI yet
--mount, --mount-exclude, --mount-cache and mounts in 0x.config.json are in the CLI
source (x1-sdk main), not in @0xlimo/cli 0.1.7 or earlier. Without --to, --mount fails:
--mount needs --to: an external data tree is only for a self-hosted site.
Needs @x1/meshtorrent. A self-hosted origin must be served over HTTPS, because the service worker needs a secure origin (localhost is fine for testing).
#0x deploy-server
0x deploy-server [dir] [--app <id>] [--entry server.mjs] [--host <url>] [--token <t>] [--ca <pem>]Bundles the game's Node.js server and runs it on 0x. Players reach it at https://play.0x.limo/x1/game/<app>/. With socket.io, the path is /x1/game/<app>/socket.io.
| Flag | Default | Meaning |
|---|---|---|
--app <id> | server.app, else id in 0x.config.json | The app id. On 0x.limo it must be one of your hosted sites. |
--entry <file> | server.entry, else server.mjs | The file the host starts |
--host <url> | ZEROX_HOST_URL, else https://api.0x.limo/x1/host | The game-server host |
--token <t> | ZEROX_TOKEN, ZEROX_PUBLISH_TOKEN, else the saved login | Your developer token |
--ca <pem> | ZEROX_CA | A private CA, for staging hosts |
The bundle is the game directory without node_modules, .x1, .git, swarm and .x1-server.tgz. @0xlimo/* and local (file:, link:, workspace:) dependencies are packed into .x1-vendor/ for you, because the host installs from the npm registry only. Run npm install first. The upload is PUT /v1/servers/<app>?entry=… (gzip tar).
stdout: {release, state, ready, url, …}. If the server isn't answering HTTP yet, the progress line says so: check 0x server logs.
Errors:
no app id: --app <id> or "id" in 0x.config.jsonserver.mjs not found in <dir> (--entry <file>)<dir> has no package.json<name> is a local dependency but node_modules/<name> is missing (npm install first)not signed in: 0x login, or ZEROX_TOKEN=<developer token>- from the host:
bundle over 50 MB,limit: 2 running servers per developer, and an error when the app id isn't one of your sites
The environment and the sandbox are described in Hosting limits, hosted game servers.
#0x server
0x server <status|logs|stop|start|list> [app] [--tail 200] [--host <url>] [--token <t>] [--ca <pem>]| Subcommand | Call | Prints |
|---|---|---|
status [app] | GET /v1/servers/<app> (no app and no config: GET /v1/servers) | State, restarts, CPU and memory |
logs [app] [--tail N] | GET /v1/servers/<app>/logs?tail=N (default 200) | Your console output plus the host's notes (install, start, restarts) |
stop [app], start [app] | POST /v1/servers/<app>/stop, /start | The new state |
list | GET /v1/servers | All your servers |
app defaults to server.app, else id in 0x.config.json in the current directory.
#0x submit
0x submit [dir] [--url <https url>] [--type web|hosted-server|paper] [--site <id> --site-version <n>]
[--id <listing id>] [--capsule <png>] [--age <rating>] [--backend <url>] [--token <t>]
[--source <spec>] [--build-file 0x.build.json] [--source-access public|deploy-key|token] [--source-token-file <f>]
0x submit status [id]
0x submit source-status [id]
0x submit deploy-key <id>Submits the store listing for review (POST /v1/listings). The body comes from 0x.config.json (id, name, tagline, description, tags, and the listing section) plus the art files it names, base64-encoded. It prints the automatic pre-check results to stderr. stdout is {listing, id, version, status, precheck_ok, source}.
| Flag | Meaning |
|---|---|
--site <id> --site-version <n> | Lists a hosted site version. Its origin becomes the play URL (this drops listing.play.url). |
--url <https url> | The page players open, for a game hosted elsewhere |
--type <t> | web (default), hosted-server or paper (listing.play.type) |
--id <id> | The listing id. Default: id in 0x.config.json. |
--capsule <file> | The capsule PNG (listing.capsule). It must end in .png. |
--age <rating> | everyone, teen, mature or adults-only (listing.age_rating) |
--release <stage> | demo (a playable demo of an upcoming release) or full (listing.release). Left out, the game keeps its stage. See Release types. |
--backend <url> | The API. Default: ZEROX_BACKEND, else the saved login's API. |
--token <t> | Default: ZEROX_TOKEN, else the saved login's publish token |
--source <spec> | Publishes the source with the listing: git:<url>#<40-hex commit>, ipfs:<cid>, or torrent:<infohash> / torrent:<magnet:…>. 0x rebuilds it and compares the output with what players download. |
--build-file <f> | The build recipe in the source. Default: 0x.build.json, or listing.source.build. |
--source-access <a> | For git: public (default), deploy-key (add the key from 0x submit deploy-key), or token |
--source-token-file <f> | A file holding a read-only access token, for --source-access token |
The price is always sent as "free". If there is no --url, --site or listing.play.url, "origin" from 0x.config.json is used as the play URL.
| Subcommand | Prints |
|---|---|
status | Each of your listings: id, listing, version, status, live, appid, review_note, issues counts |
status <id> | One listing with every version |
source-status [id] | Each version's source check: job, locator, commit, verdict, files matched, problems, AI risk |
deploy-key <id> | The read-only SSH deploy key to add to a private repository (key on stdout, fingerprint on stderr) |
Build recipe (0x.build.json):
{ "image": "node@sha256:<64 hex>", "steps": ["npm ci", "npm run build"], "output": "dist", "env": { "NODE_ENV": "production" } }The image must be pinned by digest. steps is 1–50 shell lines. output is a relative directory. env names are UPPER_CASE and can't be X1_*, HOME or PATH.
Errors: capsule <f>: must be a .png, no backend: pass --backend <url> or set ZEROX_BACKEND, not signed in: …, --source git:<url>#<commit>: the full commit id is required (branches and tags move), and the API's validation messages. See Listing fields.
#0x issues
0x issues [listing] [--json]
0x issues show <id> [--json]
0x issues reply <id> "<message>" [--fixed-in <version>] [--json]Shows the review issues the store's reviewers raised about your listings, and lets you answer them.
| Form | Call | What it does |
|---|---|---|
0x issues [listing] | GET /v1/listings/issues or /v1/listings/<listing>/issues | Your issues, active first: counts of open, waiting for you, and new |
show <id> | GET /v1/listings/issues/<id> | One issue with its thread (marks it read) |
reply <id> "<msg>" | POST /v1/listings/issues/<id>/reply | Answers it. --fixed-in <n> names the listing version that fixes it. |
States: open (waiting for you), reopened, replied, resolved, wontfix. --json prints the raw API response. --backend and --token work as for 0x submit.
#0x script
0x script publish [dir] [--check] [--notes "..."] [--no-sign] [--json]
0x script status [id[@version]] [--json]
0x script withdraw <id>@<version>
0x script capabilities [--json]Publishes 0x scripts into worlds (see Publishing scripts to worlds). It needs 0x CLI 0.1.7 or newer (it brings @x1/script 0.2). npx x1-script pack|submit|status|withdraw does the same from a project's own @x1/script. 0x script --help prints the usage.
| Form | Call | What it does |
|---|---|---|
publish [dir] | POST /v1/scriptbus/packages | Builds x1.json's scripts, bundles them with their sources into dist/package.json, signs the bundle with ~/.config/0x1/script-signing.key and uploads it for review |
status | GET /v1/scriptbus/packages | Your packages: their versions and statuses, and their installs |
status <id>@<version> | GET /v1/scriptbus/packages/<id>/<version> | One version's review report, its decisions and its open review issues |
withdraw <id>@<version> | POST /v1/scriptbus/packages/<id>/<version>/withdraw | Withdraws a version that is not decided yet |
capabilities | GET /v1/scriptbus/packages/capabilities | What you can ask for, budget maxima, and the worlds with their regions |
Errors: x1.json has N problem(s) (each one listed), versions are immutable, bump the version, this experience's uploads are signed, signed with another key, and experience <id> is someone else's. --backend and --token work as for 0x submit.
#0x source check
0x source check [dir] [--against <dir> | --against-url <origin> | --site <id> --site-version <n>]
[--build-file <f>] [--no-build] [--no-scan] [--source-date-epoch <s>] [--backend <url>] [--token <t>]Runs locally what the reviewers run on your source, before you submit.
- Scan. Sends the tree (tar, at most 50 MB,
.gitexcluded) toPOST /v1/sourcecheck/scan, a dry run that stores nothing. Prints the findings and the worst severity. Skip it with--no-scan. - Build. If
0x.build.jsonexists, runs the recipe in Docker with the checker's sandbox: no network, read-only root, uid 65534, all capabilities dropped, 8 GiB memory, 4 CPUs, a 30-minute timeout.SOURCE_DATE_EPOCHis the last commit time. Override it with--source-date-epoch. Skip the build with--no-build. - Compare. Compares the built files with a directory (
--against), a live origin (--against-url), or a hosted version (--site/--site-version).
stdout: {scan: {total, worst}, build, compare: {verdict, matched, total, problems}}. The command exits with 3 when the comparison isn't a match. Needs Docker for the build step.
#0x assets
0x assets import --game gta5 [--path <install>] [--recipes <file|dir>] [--cache <dir>] [--force] [--json]
0x assets fallback [--recipes <file|dir>] --out <dir>
0x assets locate --game gta5 [--path <dir>]Bring-your-own assets (@0xlimo/byo-assets): pinned, deterministic recipes that convert files from your own installed copy of a game into web formats.
| Subcommand | What it does |
|---|---|
import | Runs the recipes against your install into the cache ($ZEROX_BYO_CACHE, default ~/.cache/0x/byo). Exits with 2 if any recipe ends mismatch or error. |
fallback | Writes the 0x-owned stand-in assets of the recipes to --out |
locate | Prints the install it finds (Steam libraries are detected automatically) |
0x assets with no subcommand prints its usage. An unknown subcommand exits with 64.
#0x paper
Not available on 0x.limo
0x paper (bring your own Minecraft server) is not on production yet. api.0x.limo/byo/* answers 503. The command is documented for completeness.
0x paper add <host:port> [--name N] [--description D] [--wait]
0x paper verify <id>
0x paper status [id]
0x paper channels <id> <file|->
0x paper remove <id>
# options: --service <url> (default $ZEROX_BYO_URL, else https://api.0x.limo/byo/) --insecure (accept a private CA)add registers the server and prints a token to put in its MOTD. --wait re-checks every 10 s for up to 10 minutes. verify checks the MOTD and provisions an offload gateway. channels sets the gateway's fan-out channel declarations. remove stops the gateway and withdraws the listing. Management keys are kept in ~/.config/0x/paper.json (mode 600; the directory is ZEROX_CONFIG_DIR).
