CLI Reference

The binary is one self-contained command with several subcommands. Download for your platform from the install page; run yourspace with no arguments for a synopsis, or yourspace <command> --help for the exhaustive flag list on any one command.

Commands

login

Prompts for an API token, verifies it against the server before writing anything to disk, and stores it at $HOME/.yourspace/token with mode 0600. The containing directory is created with mode 0700 so other users on a shared host can't read it.

$ yourspace login
Mint a token at https://api.yo.urspace.net/tokens, then paste it.
token: ys_live_•••••••••••••••••
saved → /home/me/.yourspace/token

Flags:

• --token <value> (-t) — skip the prompt and store the given value directly.
• --no-verify — skip the pre-write API check. Useful for offline setups; you'll only discover a bad paste at the next deploy.

For CI, pipe the token in on stdin: echo "$YOURSPACE_TOKEN" | yourspace login takes the first line without opening a prompt.

init

Usage: yourspace init [<site-name>]

$ yourspace init
  site name [my-site]:
  ✓ my-site is available
  static output [dist]:
  ✓ wrote yourspace.yml
  next step: run `yourspace deploy` to ship it

Walks you through a minimal yourspace.yml. Accept defaults with <Enter> to use the current directory name as the site name. The Init & Routing guide covers the routing block; the Config Reference lists every field.

Flags:

• --name <value> (-n) — pre-fill the site name (skips that prompt).
• --dist <value> (-d) — pre-fill the build output directory (skips that prompt).
• --force (-f) — overwrite an existing yourspace.yml instead of refusing to clobber it.
• --yes (-y) — non-interactive: accept all defaults / pre-filled values without prompting. Pairs with --name / --dist for scripted scaffolding.

setup

A first-time walk that runs init, login, and deploy end-to-end without forcing you to remember the order. Step 1 scaffolds yourspace.yml (skipped if one already exists). Step 2 prompts for an API token if there isn't one yet — the prompt drops directly into login's validate-and-save path so a typo gets caught before disk-write, with up to three retry attempts before the command exits non-zero. Step 3 confirms then deploys.

Pre-flight checks fire between steps: a missing build.dist directory warns before the deploy step (so you can build first instead of failing late); a site name that already exists on the platform warns that the deploy will replace its contents.

yourspace setup
yourspace setup -y                 # auto-confirm prompts (CI mode); long form: --yes
yourspace setup --dir ./my-site    # operate on a sibling directory

For an interactive form-based variant, yourspace setup-tui (held back from public dist while it matures) renders the same flow as a full-screen TUI.

doctor

Runs a state checklist against your current environment and project — the same pre-flight checks setup does, but standalone so you can answer "am I ready to deploy?" or "why did the last deploy fail?" without committing to a deploy.

Each check is one of OK / Warn / Fail / Skip. Skips fire when a prerequisite check failed (no API auth check without a token, etc.). Warnings don't fail the command — they're surfaced for human attention but a deploy in that state fails honestly with a clear message anyway. Failures exit non-zero so you can guard yourspace doctor && yourspace deploy in a CI pipeline.

Checks run, in order:

1. API token — present (env var or stored login file).
2. yourspace.yml — found in the project directory.
3. YAML format — parses; name: field present.
4. Build output — the build.dist directory exists.
5. API auth — token validates against the API.
6. Site state — site name exists on the platform vs. is available.
7. Logs endpoint — per-site logs are reachable for this site.

yourspace doctor                   # check the current directory
yourspace doctor --dir ./my-site   # check a sibling directory

update

Replace this binary in place with the latest published release. update reads the published manifest, compares the running binary's checksum to the latest build for your OS/architecture, and — when they differ — asks you to confirm, then downloads, verifies, health-checks, and atomically swaps the new binary over this one.

The current binary is never touched until a fully downloaded, checksum-verified, and runnable replacement is in hand (the new binary has to run and report the expected version before the swap), so an interrupted or failed update never leaves you without a working yourspace. A run that downloaded the new binary but couldn't install it leaves the verified download staged next to the binary; the next run resumes from it without re-downloading.

yourspace update           # prompt for confirmation, then install the latest release
yourspace update --check   # report whether an update is available, without installing
yourspace update -y        # install without the confirmation prompt (CI / non-interactive)

If the binary lives in a directory you can't write to (a system path like /usr/local/bin owned by root), update says so and bails before downloading anything — re-run with elevated privileges, or update through whatever package manager installed it. In-place update isn't wired up on Windows yet; there the new binary is downloaded and verified and update tells you where to move it.

Flags:

• --check — report whether an update is available for your platform, but don't install it.
• --yes (-y) — skip the confirmation prompt and install without asking. For CI / non-interactive use.

ls

$ yourspace ls
NAME        VERSION  NODES  LAST DEPLOY
my-blog     v4       22     2026-04-22T09:12:00Z
side-proj   v1       22     2026-04-23T17:03:00Z

Pass --json for a stable machine-readable shape. The default output is tab-aligned for terminal reading and column -t pipelines.

status

Usage: yourspace status [<site-name>]

$ yourspace status
  my-site (v3) — live
  nodes: iad, cdg, gru, sin

Without arguments, reads the name: field from the local yourspace.yml. Pass a site name to check any site you own: yourspace status my-blog. --json returns the same data with stable keys. Pass --metrics (-m) to also show the site's recent request timeline — a one-line summary (total requests, sample count, window start, tick interval) plus the sample-by-sample series; it makes a second call to the per-site metrics endpoint, so it's off by default to keep a bare status a single fast lookup. Use --dir <path> to read yourspace.yml from somewhere other than the current directory.

open

Usage: yourspace open [<site-name>]

Opens the deployed site URL in your default browser. Like status, the site is inferred from the cwd's yourspace.yml when no positional argument is given — the most common shape is cd my-project && yourspace open. The URL is derived from the configured API endpoint by stripping the api. prefix from the host: https://api.yo.urspace.net → https://my-site.yo.urspace.net.

yourspace open                  # opens <name>.yo.urspace.net for the cwd's site
yourspace open my-blog          # opens my-blog.yo.urspace.net regardless of cwd
yourspace open -p               # print the URL instead of launching a browser; long form: --print
yourspace open -u <url>         # open this URL verbatim (custom-domain-only deploys); long form: --url

When the platform-canonical opener (open on macOS, xdg-open on Linux, cmd /c start on Windows) isn't available — minimal Linux without xdg-utils, headless SSH, CI — the URL prints to stdout instead of failing, so you can copy-paste.

logs

Usage: yourspace logs [<site-name>]

Tail the most recent access-log entries for a site. Filtering happens server-side: only requests to the site's canonical hostname (or any verified custom domains) appear. The default rendering trims each entry to time · status · method · host · uri; pass --json to keep every field the server emits for piping through jq.

yourspace logs                       # last 50 entries for the cwd's site
yourspace logs my-blog -n 200        # explicit site + larger window (head/tail -n convention); long form: --tail 200
yourspace logs -s 15m                # only entries from the last 15 minutes; long form: --since 15m
yourspace logs --since 2026-04-27T10:00:00Z  # absolute timestamp (RFC3339)
yourspace logs -j | jq               # raw entries with every field the server emits; long form: --json

Status-aware colouring fires only when stdout is a TTY: 5xx red, 4xx yellow, 3xx blue, 2xx muted. Piped output stays plain so a tee logfile capture doesn't fill up with terminal escapes. Entry content is sanitised before render — a hostile request URI carrying ANSI escapes or Unicode bidi overrides cannot move your cursor or flip your text direction.

deploy

$ yourspace deploy
  ✓ Validating yourspace.yml
  ✓ Bundled dist/ — 12 files, 4.8 KB
  ✓ Uploaded (v1)
  ✓ live → https://my-site.yo.urspace.net

Reads yourspace.yml, tars the directory declared under build.dist, and streams the bundle to api.yo.urspace.net in one multipart upload. Every successful deploy gets a fresh version number; previous versions remain accessible to the backup and rollback flows. See the Deploy page for the full flow and the tl;dr curl alternative.

Flags:

• --dist <value> (-d) — bundle this subdirectory instead of build.dist from the YAML. Useful for one-off "ship what's in out/ instead" deploys without editing the config.
• --bundle <file> (-b) — upload a pre-built .tar.gz archive verbatim instead of packing build.dist (the client validates it's gzip, then ships the bytes as-is). For CI that already produced the bundle, or to deploy an artifact built elsewhere. Mutually exclusive with --dist; yourspace.yml is still read from --dir.
• --dry-run — pre-flight: pack the bundle, validate the YAML, probe site state, but don't upload. Returns a summary of what would have shipped (file count, byte size, would-create vs would-replace classification). Pairs with --json for a machine-readable summary in CI guards.
• --force (-f) — bypass server-side dup detection. The server hashes every uploaded bundle and short-circuits a redeploy when the hash matches the live slot — CI re-runs against the same commit are no-ops by default. --force advances the slots anyway, which evicts the previous deploy from the rollback slot. Use only when you want to deliberately invalidate the rollback target.
• --open (-o) — after a successful deploy, open the deployed URL in your default browser. Off by default so CI deploys don't get surprised by browser launches; pass when working interactively. No-op for --dry-run, --json, and dup-detected redeploys (the live URL hasn't changed). A future settings.json mechanism (planned) will let interactive users opt into "always open" without re-passing the flag.

Bundle size limits

The platform caps deploy bundle size on two axes:

• Compressed (.tar.gz): 10 MB by default. The server checks the multipart upload's reported size before reading the bundle, so an over-cap deploy fails fast with 413 Request Entity Too Large naming the actual size + the cap.
• Unpacked (sum of regular-file bytes during extraction): 25 MB by default. The server tracks running bytes during the tar walk and rejects with 400 Bad Request naming the entry that pushed past the cap.

If your deploy hits a cap, the response names the actual size + the configured limit so you can trim the bundle accordingly. yourspace doctor runs the same compressed-size check locally and warns when your bundle is approaching the cap before you upload.

rollback

Usage: yourspace rollback <site-name> [--version <N>]

Swap a site back to its previous deploy, or to a specific retained version when --version names one explicitly. The platform retains your recent deploys so rollback is a live-version pointer flip — no re-upload, no traffic gap.

yourspace rollback my-blog              # swap to the prior deploy
yourspace rollback my-blog --version 7  # swap to a specific retained version
yourspace rollback my-blog -j           # JSON for scripts (long form: --json)

Rollback is symmetric — running yourspace rollback again swaps back to the deploy that was just demoted.

Behind the scenes, the CLI lists retained versions (GET /v1/sites/<name>/deploys), picks the most-recently-deployed non-current one, and POSTs that version number to /v1/sites/<name>/version. The version endpoint is idempotent: re-posting the same target is a clean no-op regardless of what's currently live.

Errors with a specific "nothing to roll back to" message when the site has only ever had one deploy, or when every redeploy carried the same bundle hash so no second version was ever retained. See deploy — its force option advances the version list on a future deploy.

delete

Usage: yourspace delete <site-name>

Tear down a site and remove it from every node. The site name is required as a positional argument — there is no yourspace.yml fallback, because a reflex yourspace delete in a project directory must never remove the production site without an argument.

$ yourspace delete my-site
About to delete "my-site" from all nodes. This cannot be undone.
Type "my-site" to confirm: my-site
✓ deleted "my-site"

Default behavior prompts you to re-type the site name. Re-typing (rather than y/N) forces you to read the name from the prompt before the command proceeds, which resists a reflex keystroke.

For scripted use, pass --yes-really-delete to skip the prompt:

yourspace delete my-site --yes-really-delete

domain

Bind, verify, list, or remove a custom hostname (e.g. foobar.com) on a site. Four subverbs under one verb group:

domain ls

Usage: yourspace domain ls <site-name>

$ yourspace domain ls my-site
DOMAIN       STATUS     LAST CHECK  DETAIL
foo.com      verified   10m ago
bar.com      pending    1h ago      TXT record missing

Lists every custom domain bound to a site with its verification status (verified / pending) and last-check timestamp. Use this to see which hostnames are configured before running domain remove. Pass --json for a stable machine-readable shape.

domain add

Usage: yourspace domain add <site-name> <domain>

$ yourspace domain add my-site foo.com
✓ binding created for foo.com

publish this DNS record to prove control, then run:
  yourspace domain verify my-site foo.com

  _yourspace-verify.foo.com.  IN  TXT  "ys-verify-•••"

Creates an unverified binding and prints the DNS TXT record to publish. The server never serves traffic for the hostname until verification succeeds — this step only reserves the binding on the yourspace side. Publish the printed record at your DNS provider, then run yourspace domain verify.

domain verify

Usage: yourspace domain verify <site-name> <domain>

$ yourspace domain verify my-site foo.com
✓ foo.com verified (just now)

Triggers a DNS lookup against _yourspace-verify.<domain> and compares the TXT record to the token minted by domain add. On success the binding is marked verified and the platform starts serving traffic on that hostname; on failure the server's diagnostic (TXT missing, TXT mismatch, resolver error) surfaces through unchanged so you can see what went wrong.

domain remove

Usage: yourspace domain remove <site-name> <domain>

$ yourspace domain remove my-site foo.com
About to remove "foo.com" from "my-site". Traffic to that host will stop serving.
Tip: foo.com is currently verified — consider updating or removing its DNS records first so visitors don't hit a stale-cert or SNI error during the transition.
Type "foo.com" to confirm: foo.com
✓ removed "foo.com" from "my-site"

Tears down a binding. Traffic to that hostname stops serving. Same re-type confirmation as yourspace delete — type the domain name to confirm. For scripted use, pass --yes-really-remove. When the binding is already verified the prompt includes a DNS-housekeeping tip: update or remove the CNAME at your DNS provider first so visitors don't hit a stale-cert or SNI error during the transition.

token

Create, list, rotate, or revoke API tokens. Subverbs under one verb group; the customer-facing pre-alpha cohort uses these to bootstrap CI credentials and rotate stored bearers without operator round-trip. token create is the ergonomic deploy-credential surface.

token create

Usage: yourspace token create --owner <id> [--scope deploy] [--site my-blog] [--expires 30d] [--label X]

Mints a scoped, owner-bound deploy credential and prints the plaintext bearer once — copy it into your secret store immediately, the server cannot show it again. This is the recommended way to issue a CI / agent deploy token: yourspace token create --owner me --scope deploy --site my-blog --expires 30d, then YOURSPACE_TOKEN=ys_live_… yourspace deploy.

--owner (-o) names the principal (typically your account id or email) and is required. --scope defaults to deploy (valid values read, deploy, write, admin). --site is repeatable and names a site the token may deploy (e.g. my-blog or writers/*); it records a per-site capability on the token. Note that per-site enforcement is not yet active — until the capability matcher lands, a deploy token authorizes deploys to all of the owner's sites; omit --site for that all-sites grant explicitly. --expires accepts a duration with day (d) and week (w) units in addition to Go's h/m/s/etc. (30d and 720h both mean 30 days; 4w is 28 days) and is enforced server-side; empty leaves the token without expiry. --label (-l) attaches a human-readable description (operator-side only).

token ls

Usage: yourspace token ls

Lists every visible token. A tester-tier credential sees only its own tokens; a platform-tier credential sees all. Pass --json for the raw view records. Sensitive fields (lookup hashes, signature material) are absent from the output by design — they live on the server, not on the wire.

token rotate

Usage: yourspace token rotate <token-id>

Generates a new plaintext for an existing token id and prints it once. The previous plaintext stops authenticating immediately — update any stored credential before sending the next request, or you'll see 401s until you do.

token revoke

Usage: yourspace token revoke <token-id>

Soft-deletes a token. Idempotent — re-revoking the same id returns success silently. After revocation, requests bearing that token get a distinct 410 rather than a generic 401 so an audit-time read of the failure can tell "the token was revoked" apart from "the token never existed."

completion

Usage: yourspace completion [--type <bash|zsh|fish>] [--static]

Emits a shell completion script for the named shell to stdout. Pipe or redirect the output to the location your shell loads completions from:

• bash — source it from ~/.bashrc, or drop under /etc/bash_completion.d/ (system-wide) / ~/.local/share/bash-completion/completions/yourspace (per-user).
• zsh — drop it into a directory on $fpath as _yourspace. A common per-user layout is ~/.zfunc/_yourspace with fpath+=~/.zfunc and autoload -U compinit && compinit in .zshrc.
• fish — drop it at ~/.config/fish/completions/yourspace.fish.

If you omit --type, the shell is inferred from your $SHELL environment variable. Pass --type explicitly if you're piping from a non-interactive shell or want to install completion for a shell other than your login one.

Two modes: by default the script installs a tiny callback shim that subprocess-spawns yourspace __complete on every tab press — completion always matches the installed binary, no re-emit needed after upgrades. With --static, the script enumerates the command tree at emit time instead; new commands added in a future yourspace release then require re-running completion and reloading your shell. Trade-offs:

• Dynamic (default): always fresh — completion tracks the installed binary with no re-emit. Each tab press spawns the binary (~5-30ms latency; imperceptible for casual use, perceptible if you mash-tab).
• Static (--static): zero per-tab cost. Stale after a binary update — operators must re-emit.

Both modes complete the verb itself (yourspace <tab>), one level of subcommand (yourspace domain <tab> lists add, ls, remove, verify), and per-cmd long-form flag names (yourspace deploy --<tab> surfaces deploy's flags + shared ones like --api / --json). Descriptions surface in zsh and fish; bash's completion model can't carry them. Short-form flag completion and flag-value completion are not yet wired in either mode.

Flags:

• --type <shell> (short -t) — one of bash, zsh, fish. When omitted, inferred from $SHELL. Returns a usage error if $SHELL is unset or names a shell other than the three supported.
• --static — emit the static enumeration script instead of the dynamic shim. Default dynamic.

Global flags

A few flags work the same way across most commands and are documented here once instead of on every subcommand. Long forms (--name) and POSIX short forms (-n) parse identically; joined shorts (-tn50) and --name=value / -n=value / -n value all work.

• --api <url> — override the API endpoint for this invocation. Every command that talks to the API accepts it; defaults to $YOURSPACE_API or https://api.yo.urspace.net. No short alias (-a is "all" in too many other tools).
• --json (-j) — print the raw server response as JSON (no human formatting). Available on every command that returns structured data: ls, status, logs, deploy --dry-run. Use for jq pipelines or CI guards.
• --dir <path> — operate on a project directory other than the cwd. Available on every project-scoped command (init, setup, doctor, status, open, logs, deploy). Defaults to .. No short alias.

Per-command short flags are listed in each command's section above.

Environment variables

• YOURSPACE_TOKEN — bearer token for API calls. Overrides the token stored by yourspace login.
• YOURSPACE_API — override the default API URL (https://api.yo.urspace.net). Useful for staging or self-hosted deployments. Every subcommand also takes a one-off --api <url> flag.
• YOURSPACE_DIR — override the configuration directory. Defaults to $HOME/.yourspace.