CLI Reference

The binary is one self-contained command with several subcommands. Install it via curl, go install, or your distribution of choice; 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: `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

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

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.

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, stats, 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.