0xDocs 0x.limo

Docs / 0x CLI

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

bash
0x init [<template> [dir]] [--list]
0x new [dir] --template <template>

Creates a starter game. With no template, or with --list, it lists the templates.

ArgumentMeaning
<template>three, phaser, babylon or canvas. The aliases three-js, threejs, babylonjs, babylon-js, vanilla and vanilla-canvas also work.
dirTarget 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

bash
0x dev [dir] [--port 5173] [--no-seed] [--verbose]

Serves the game locally the way 0x serves it, at http://localhost:<port>/.

FlagDefaultMeaning
--port <n>5173Port to listen on (127.0.0.1)
--no-seedseeding onDon't start the local seeder
--verboseoffPrint the seeder's log

It runs:

  • a static server with single-range support, serving the 0x runtime files (x1-sw.js, x1/…) and an x1.json;
  • a meshtorrent tracker behind /p2p/;
  • a seeder of every file in the swarm manifest;
  • a development broadcast service at /x1/bcast/server and /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

bash
0x login [--api <url>] [--token <0xpub_...>]
0x logout
0x whoami
FlagMeaning
--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

bash
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.

FlagMeaning
--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.
--serverAlso 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:

  1. Read 0x.config.json. Upload from "dist" (default .).
  2. List the files (skipping what is never uploaded) and hash each one.
  3. If the site doesn't exist, create it (POST /v1/hosting/sites). If it belongs to someone else, stop.
  4. Open a version (POST /v1/hosting/sites/<site>/versions {files, csp}). The service answers with the hashes it lacks.
  5. Upload them, 6 at a time (PUT /v1/hosting/blobs/<sha256>). Uploads that get 429 or 5xx are retried up to 5 times.
  6. 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:

json
{
  "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.json
  • the site name "…" belongs to another developer: pick another with --site
  • upload refused: followed by one line per problem
  • the site builder refused this version: followed by the findings
  • quota and limit errors (see Hosting limits)

#0x publish --to (self-hosting)

bash
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.

FlagMeaning
--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

bash
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.

FlagDefaultMeaning
--app <id>server.app, else id in 0x.config.jsonThe app id. On 0x.limo it must be one of your hosted sites.
--entry <file>server.entry, else server.mjsThe file the host starts
--host <url>ZEROX_HOST_URL, else https://api.0x.limo/x1/hostThe game-server host
--token <t>ZEROX_TOKEN, ZEROX_PUBLISH_TOKEN, else the saved loginYour developer token
--ca <pem>ZEROX_CAA 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.json
  • server.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

bash
0x server <status|logs|stop|start|list> [app] [--tail 200] [--host <url>] [--token <t>] [--ca <pem>]
SubcommandCallPrints
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, /startThe new state
listGET /v1/serversAll your servers

app defaults to server.app, else id in 0x.config.json in the current directory.

#0x submit

bash
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}.

FlagMeaning
--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.

SubcommandPrints
statusEach 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):

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

bash
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.

FormCallWhat it does
0x issues [listing]GET /v1/listings/issues or /v1/listings/<listing>/issuesYour 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>/replyAnswers 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

bash
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.

FormCallWhat it does
publish [dir]POST /v1/scriptbus/packagesBuilds 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
statusGET /v1/scriptbus/packagesYour 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>/withdrawWithdraws a version that is not decided yet
capabilitiesGET /v1/scriptbus/packages/capabilitiesWhat 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

bash
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.

  1. Scan. Sends the tree (tar, at most 50 MB, .git excluded) to POST /v1/sourcecheck/scan, a dry run that stores nothing. Prints the findings and the worst severity. Skip it with --no-scan.
  2. Build. If 0x.build.json exists, 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_EPOCH is the last commit time. Override it with --source-date-epoch. Skip the build with --no-build.
  3. 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

bash
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.

SubcommandWhat it does
importRuns 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.
fallbackWrites the 0x-owned stand-in assets of the recipes to --out
locatePrints 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.

bash
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).