yothere

CLI reference

Every yothere command and the module entry points, with what each one does.

Beta · signup open

yothere is in open beta. Create your workspace at app.yothere.ai/signup, your first 7 days are free, no credit card. Then the Founding plan is $20/mo.

yothere is the single front door to the fleet. Run yothere --help for the built-in summary, yothere --version for the installed version, or yothere <command> --help for a command’s flags. This page enumerates every subcommand and the python -m ... module entry points. Spawning threads is pure file I/O and safe to run in-session; advancing them is the runner’s or the leaser’s job.

Threads

Command What it does
yothere init [--demo] First-run setup: create the ~/.yothere layout and detect or wire a brain. Idempotent and non-destructive. --demo drives a live zero-key demo thread to done.
yothere spawn "<task>" Spawn one or more threads from a natural-language task. A reminder-shaped task (“remind me to X”) is captured to your reminders file instead of spawning.
yothere preset <key> [arg] Spawn a named preset, e.g. yothere preset news-scan "agentic commerce". It runs immediately, like any other hail.
yothere presets List available presets with their ETA and read-only or gated-send label.
yothere note "<text>" Capture a reminder to your reminders file (no thread).
yothere mode <id> <auto|planning> Set an existing thread’s scope.
yothere list List live threads and their state in a table.
yothere show <id> Show one thread: state, any open question and options, summary, and the first lines of the plan.
yothere focus <id> Pin the focus thread.
yothere unfocus Clear the focus pin.
yothere reply <id> [text] Answer a blocked thread, which flips it to resumed so the runner re-advances it. Text is positional or piped via stdin.
yothere resume <id> Flip a thread to resumed (re-advance it) without adding a reply.
yothere status Print a prose summary of the fleet (text).
yothere board [--open] Build the standalone fleet board. --open opens it in your browser.
yothere tasks <discover|refresh|show> Brain-discovered task source: find where your to-dos live, refresh the cache, or show the current source.
yothere park <id> Pause a thread.
yothere kill <id> [--archive] [--force] Remove a thread, or archive a recoverable copy.
Note A hail needs a verb the parser knows. Read and draft verbs (research, scan, draft, review, compare, and others) and code verbs (fix, add, implement, refactor, update, rename, debug, and others) both work. ship, merge, deploy and push are deliberately NOT spawn verbs: they are the words you use to APPROVE a result, so they would otherwise create a thread instead of approving the one on screen. yothere spawn "ship it", "merge the branch" and "deploy to prod" are all refused by design.

Code (workspaces)

A workspace is a git repo you already have on this machine. yothere never clones and never holds a git credential: it is a remote control for your box, so it can build exactly what you could build from your own terminal, and nothing more.

Command What it does
yothere workspace add <name> <path> [--alias A,B] Register a local git repo under a name (--alias adds extra names voice can match). It must already be a git repo; yothere does not clone.
yothere workspace list List registered workspaces, their paths, their default branch, and any live thread worktrees.
yothere workspace rm <name> Deregister a workspace. The repo on disk is untouched.
yothere spawn --repo <alias> "<task>" Bind the thread to that repo. Its turns run in their own git worktree, on their own branch. 
yothere workspace add site ~/code/my-site
yothere spawn --repo site "fix the layout shift on the pricing page"

A bound thread never runs in your working tree. It gets a worktree of its own under ~/.yothere/worktrees/, on a branch named yothere/<thread-id>-<slug>, so three code threads are three HEADs that cannot collide with each other or with what you are editing. The agent reads the repo, makes the change, runs the tests, and commits on that branch. You read the branch from your own checkout (git log yothere/..., git diff main...yothere/...) and you decide what happens to it.

You can also just name the repo in the hail (“in site, fix the layout shift on the pricing page”): one named repo binds the thread, and two ask rather than guess. With exactly one workspace registered, a hail that names something code-shaped (a test, a bug, an endpoint, the CLI, the config) binds to it with no flag at all. A vaguer hail (“fix the layout shift on the pricing page”) names nothing code-shaped, so it stays unbound and runs in YOTHERE_WORK_DIR like any other thread: pass --repo when you mean a repo. A reading task is never bound.

The agent cannot push. Ship it can. git push, gh api and the mutating gh subcommands are on a never-grant list in the send-gate: the approval path cannot mint a grant for them, so a worker turn can never publish, no matter what you approve. Publishing is your call, and yothere carries it out: press Ship it on the diff and it pushes the branch and opens the PR as you, with the login already on your machine, as plain git outside the turn. It is a rule in the gate, not a sandbox: see Trust for where that ends.

Machine

Command What it does
yothere doctor [--json] [--probe-brain] [--bundle] Diagnose the install: pass, warn, fail, or skip, each with a one-line fix. See below.
yothere login [--url <cp>] [--token <token>] [--label <name>] Pair this machine with the hosted control plane. By default it runs the browser device flow: it prints a short pairing code (rendered XXXX-XXXX) plus a link to app.yothere.ai/activate, where you confirm which machine is asking and pick its permission tier, and it saves a per-device credential at ~/.yothere/credentials.json (mode 0600, no compute keys). The device flow covers headless and SSH-only boxes too: open the printed link in a browser on any device. --url defaults to https://app.yothere.ai, so pass it only for a self-hosted control plane. --token redeems an operator-minted single-use pairing token (see yothere admin pair-token below), the path for unattended provisioning and self-host break-glass. --label names the machine.
yothere service [run|install|uninstall|status] The BYO-compute leaser: long-poll the paired control plane, run each leased turn locally on your agent CLI, push the result back. See below.
yothere devices <list|revoke <device_id>> List or de-authorise this owner’s paired machines, from any other paired machine.
yothere capabilities [--json] [--say] What this machine can actually do right now: git, gh auth, installed harnesses, connected repos. --say prints the spoken answer, as the phone would say it.
yothere setup-github [--force] Sign this machine in to GitHub via the gh device flow (no TTY needed, no token on disk to paste).
yothere local wipe [--harness] [--older-than <days>] [--dry-run] [--yes] Erase the content this box keeps on your own disk: call transcripts, call debriefs, failed-turn logs. --harness also prunes codex rollouts and your own claude session transcripts (age-bounded).
yothere feedback "<text>" Send one piece of feedback to the yothere team. On a paired machine it POSTs to the control plane; unpaired, it records locally so nothing is lost.
yothere say [--lang] [--tts] Speak the fleet summary aloud (macOS say by default).
Note Voice needs no command. It is hosted: you click Connect in the cockpit and talk to your fleet in the browser, with nothing to install and no key to bring. yothere voice and yothere listen below are local, advanced paths, not part of the normal setup.

Operator (hosted)

These run where the auth database is reachable, not on a paired laptop.

Command What it does
yothere invite create [...] Mint a signup invite code. See the flags below.
yothere passwd <email> [--password <pw>] Reset a hosted account’s password. Prompts twice unless --password is given (that flag lands in shell history; prefer the prompt). Also clears the failed-login lockout and revokes live sessions.
yothere admin funnel [--json] The activation funnel: invite, signup, first thread, second thread, day-2 return.
yothere admin nsm [--json] North-star metric: threads a user steers per week, plus day-2 returns.
yothere admin feedback [-n <n>] [--json] The latest feedback rows.
yothere admin pair-token <email> [--tier observe|workspace|full] [--send contained|open] [--label <name>] [--url <cp>] Mint a single-use pairing token for an account and print the exact yothere login --url <cp> --token <t> command to run on the machine. The token expires unclaimed after 60 minutes and is stored only as a sha256 hash. This is the operator path for unattended provisioning and self-host break-glass; interactive pairing is yothere login’s browser device flow. Revoke the resulting device with yothere devices revoke or in Settings → Machines.
yothere admin email [--json] Transactional email health: 7-day and 30-day counts, delivery rate, bounces.
yothere admin errors The server-side error tracker: busiest routes plus a recent tail.
yothere admin users List hosted accounts: tenant, email, age, budget, status.
yothere admin spend Per-tenant spend: the daily cap against today’s and total compute cost.
yothere admin suspend <email> / unsuspend <email> Block or restore an account’s login and compute. Reversible.
yothere admin delete <email> --yes Permanently delete an account. Irreversible; prefer suspend.
yothere admin jobs [tenant] List queued and leased jobs. A queued job is waiting for a paired machine; a leased one is running on it.
yothere admin cancel <tenant> <id> Park a queued job so it stops queueing. Refuses an actively-leased turn.

Key flags

spawn

yothere spawn "<task>" [--focus] [--yes] [--mode auto|planning] [--repo <alias>]

  • --focus pins the first spawned thread as the focus thread.
  • --yes spawns even on a low-confidence parse. Without it, a low-confidence task prints a clarifying question and stops (no surprise spawn). It never overrides a repo it could not resolve: a wrong repo is not something to force.
  • --mode auto|planning forces the scope. Omit it and each task is classified automatically.
  • --repo <alias> binds the thread to a registered workspace, so its turns run in that repo’s own worktree. See Code (workspaces).

preset accepts the same --focus and --mode flags: yothere preset <key> [arg] [--focus] [--mode auto|planning].

service

yothere service [--wait <s>] [--workers <n>] [--chat-workers <n>]

Bare yothere service (or yothere service run) runs the leaser in the FOREGROUND until Ctrl-C. It long-polls the paired control plane, runs each leased thread’s turn locally on the configured brain’s agent CLI (claude -p or codex exec), and pushes the result back. The turn’s working directory is YOTHERE_WORK_DIR, so run it from the project you want the agent to work in.

  • --wait is the long-poll window per request (default 25 seconds).
  • --workers is how many work turns run at once. Default 5: that is the parallelism, and it is what makes the fleet a fleet.
  • --chat-workers is a separate pool for typed questions, on top of --workers (default 2), so a reply never queues behind a long work turn. 0 collapses it back into the single work pool.

yothere service install [--dry-run] [--python <path>] [--env-file <path>] installs that same loop as an always-on unit (launchd KeepAlive on macOS, systemd Restart=always on Linux) so it survives logout and reboot. It requires a paired machine, so run yothere login first. yothere service uninstall [--dry-run] removes the unit and keeps your credentials and threads. yothere service status reports whether the unit is running.

Note The first start requires an explicit unattended-tool-use consent acknowledgement. yothere service prints the consent text and the exact one-liner to acknowledge it, then you re-run.

doctor

yothere doctor [--json] [--probe-brain] [--bundle]

Run it after install and any time something looks wrong. It checks the Python version and range (3.11 to 3.13; 3.14 is a hard fail), the installed package, the home layout, the resolved brain (including whether the Codex CLI has logged into yothere’s own CODEX_HOME), the service units, the notifier, and the network exposure, and it prints a one-line fix for every warn and fail.

  • --json is machine-readable output.
  • --probe-brain also probes the agent CLI (claude --version / codex --version) or a remote endpoint’s reachability.
  • --bundle writes a redacted diagnostics tarball (the report, a redacted env file, log tails) that is safe to attach to a public issue.

invite create

yothere invite create [--code <code>] [--uses <n>] [--budget <usd>] [--email <addr>] [--expires <iso8601>] [--send] [--note <text>]

Mints a signup invite (requires YOTHERE_AUTH_MODE=hosted). --uses defaults to 1, --budget sets the per-tenant daily cost cap in USD, --email binds the code to one address, and --expires takes an ISO 8601 timestamp (e.g. 2026-12-31T00:00:00Z). --send emails the code to --email (it needs RESEND_API_KEY), and --note adds one personal line to that email.

kill

yothere kill <id> [--archive] [--force]

  • --archive moves the thread to a recoverable archive within the fleet tree instead of deleting it.
  • A hard delete is irreversible. An interactive shell prompts for confirmation; a non-interactive caller must pass --force. Prefer --archive to keep a copy.

Local voice (advanced)

Voice on the product is hosted and needs none of this. These two commands drive a media session on your own machine and are advanced paths, not part of setup.

yothere voice [--wait <s>] [--local] [--port <n>] is the broker client: it long-polls the control plane for a WebRTC offer, runs the media session on this machine, and posts the answer back. Running the media on your machine does not keep the call to yourself: the client pushes its rolling transcript up to the control plane, where it is stored with your account and read back in the cockpit’s voice panel. --local skips the control plane entirely and boots a media host on 127.0.0.1:<port> (default 8767), which is a development path.

yothere listen [--ptt] [--once] [--lang en|es|de] [--tts say|kokoro] [--model small|medium] [--device <n>] is an experimental local microphone loop: speak to spawn, get status, reply, or capture a note. Use --ptt (press Enter to talk); --once does a single capture, routes it, and exits. It needs the voice extra installed, and it is not the supported way to talk to your fleet. Hosted voice in the cockpit is.

Module commands

A few surfaces run as Python modules rather than yothere subcommands. These are the operator-run engine and the full service installer.

Command What it does
python -m yothere.runner once Advance the fleet one tick and print the JSON summary. This is the default when no verb is given.
python -m yothere.runner loop The always-on advance engine. A single-instance file lock prevents a second loop from double-spawning workers.
python -m yothere.runner_watchdog A one-shot liveness check that nudges you if the runner is down or crashlooping. Run it on a schedule.
python -m yothere.onboarding status Print every setup step with its live state.
python -m yothere.onboarding apply <step> [--args <json>] [--yes] Apply one onboarding step. --args is JSON, --yes skips the confirmation prompt.
python -m yothere.service install [--cockpit] [--leaser] [--dry-run] [--python <path>] [--env-file <path>] The full installer, wider than yothere service install (which touches only the leaser unit). --cockpit also installs the cockpit and voice server unit, --leaser the BYO-compute leaser, --dry-run prints the plan and changes nothing.
python -m yothere.service uninstall [--dry-run] Stop and remove the units and wrappers (keeps your env and threads).
python -m yothere.service status Report the liveness of the installed units.
yothere-mcp The MCP server console script, so any MCP client can drive a fleet. Needs the mcp extra to run.
Note Every YOTHERE_* environment variable also accepts its RELAY_* sibling. Lead with the YOTHERE_* names; the RELAY_* forms are legacy aliases kept for back-compat.

Coming soon

Coming soon: scheduling There is no scheduler and no recurring hail. A hail, a preset, anything you spawn: it runs once, immediately. yothere spawn "scan the news every morning at 7" creates one thread that runs now. It is not built yet.

Next steps