tuimote / docs / cli

tuimote session

Talk to other agent sessions, and drive individual ones

Send messages, read screens, start/stop, attach, and ask questions.

tuimote session ls

List sessions

The bare command prints a sectioned dashboard: running sessions federation-wide, this repo's inactive ones, archive counters, and machine/federation summaries — each collapsed section carrying the exact command that expands it. Filters (--agent, --cwd, --running, --origin, --local, --inactive, --this-repo, --all) print the compact flat table instead; --json dumps the raw array.

--agent <AGENT>

--cwd <CWD>

--running

--json

Emit the full raw JSON array instead of the compact table. --pretty emits the same array pretty-printed

--all

Every session, every machine — the old flat dump (forensics)

--this-repo

Flat table of this repo's inactive sessions

--local

Machine-local sessions only (no @machine: rows)

--inactive

Inactive sessions only (combines with the other expanders)

--origin <ORIGIN>

Sessions from one peer machine, by its label (--origin macbook)

--archived

Archived-session view: counts and the per-repo breakdown

tuimote session info

Show everything tuimote recorded about one session

Pass a shorthand, or pair a session id with --agent. The default output is pipeable JSON; --human renders named sections.

[SESSION]

Session shorthand, or a session id when --agent is present

--agent <AGENT>

--cwd <CWD>

--sections <SECTIONS>

Restrict output to comma-separated sections

tuimote session start

Start a new session, or resume one with --session

tuimote session start --cwd DIR --agent claude [-m "first message"] [--pin]

--cwd <CWD>

--agent <AGENT>

--session <SESSION>

-m, --message <MESSAGE>

First message to send once the session boots (as if you typed it)

--pin

Pin the new session as this repo's entrance session

--model <MODEL>

Launch on this model instead of the harness default. Identifiers come from tuimote session models. Leaving it off is the safe answer: agents should prefer the default and ask the human when a task seems to want another model. The operator may allow only some models here; the dashboard picker is never restricted

tuimote session models

List the models each harness can start a session on, with the operator's notes on when to use them and which the CLI may ask for

The bare command prints a per-harness summary (model count + what the CLI may ask for); --all prints the full annotated catalog; --json dumps the raw catalog.

--agent <AGENT>

Only this harness (claude, codex, pi, …)

--all

The full annotated catalog instead of the per-harness summary

--json

Emit the raw JSON catalog

tuimote session stop

Kill a session's tmux pane

<SESSION>

tuimote session archive

Archive a session (soft delete — recover it from `stash`)

Pass a <slug> shorthand, or the explicit --agent/--session[/--cwd].

[SLUG]

--agent <AGENT>

--session <SESSION>

--cwd <CWD>

tuimote session delete

Delete a session permanently

Pass a <slug> shorthand, or the explicit --agent/--session[/--cwd].

[SLUG]

--agent <AGENT>

--session <SESSION>

--cwd <CWD>

tuimote session copy

Convert a session to a different harness. [experimental]

tuimote session copy <slug> --to codex

[SLUG]

--cwd <CWD>

--session <SESSION>

--from <FROM>

--to <TO>

tuimote session send

Send a message to a session's composer

tuimote session send <target> your message here

With no target it goes to this repo's pinned session (resuming it if dead). Waits until the keys actually land at a ready agent.

Sends queue by default: the message waits for the composer instead of seizing it, so a busy agent is never interrupted. --interrupt opts into the immediate behaviour. --gently is kept as a deprecated no-op alias for the queued default.

[SESSION]

Target session (shorthand, tmux name or @peer:shorthand; a peer's @ or label may be omitted when the session is unambiguous). A first word naming no session is message text (repo's pinned session is used)

[TEXT]…

--from <FROM>

--raw

--interrupt

Interrupt the session's current turn and type immediately The default queues the message for the composer; use this when the send must seize the pane now — a human nudging one session, an urgent correction to a busy agent.

--gently

Deprecated no-op alias for the queued default Kept for one release so existing scripts and muscle memory keep working; use --interrupt for the immediate behaviour.

tuimote session view

Read what's on a session's screen (read-only)

--lines N, --full, --ansi. No target = this repo's pinned session.

[SESSION]

--lines <LINES>

--full

--ansi

tuimote session attach

Attach to a session's tmux

No target = this repo's pinned session (resuming it if dead).

[SESSION]

tuimote session unpin

Clear a repo's entrance pin (inverse of `repo pin`)

With a <target> clears that session's repo; else --cwd, else this session's own repo.

[TARGET]

--cwd <CWD>

tuimote session keys

Send raw control keys to a session (C-c, Escape, Enter, arrows…)

tuimote session keys <target> C-c

Keys land verbatim — no text, no trailing Enter. Use send to type a message. Accepts tmux names (C-c, Escape, Tab), C-<letter>, or escapes (\x03, \e, \r). Multiple keys are sent in order.

[SESSION]

Target session (shorthand / tmux name / chat). A first word that doesn't resolve is treated as the first key (pinned session used)

[KEYS]…

One or more key names / sequences to send in order

tuimote session image

Attach an image to a session

tuimote session image <target> path/to.png [--caption "…"]

PNG/JPEG/GIF/WebP only. Uploads the file and types its path in the harness's own vision syntax.

<SESSION>

Target session (shorthand / tmux name / chat)

<PATH>

Path to the image file

--caption <CAPTION>

Optional caption typed alongside the path

--no-submit

Type the path without submitting (leave it in the composer)

tuimote session transcript

Print a session's transcript

Pass a <slug> shorthand. --mode picks the format (default no-tools).

[SLUG]

--agent <AGENT>

--session <SESSION>

--cwd <CWD>

--mode <MODE>

(default: no-tools)

tuimote session stub

Generate or refresh a session's one-line summary stub

Pass a <slug> shorthand, or the explicit --agent/--session pair.

[SLUG]

[TEXT]…

--agent <AGENT>

--session <SESSION>

--file <FILE>

tuimote session request

Ask a session a question and wait for its reply

tuimote session request <target> your question here

Blocks until it answers. --keep leaves the session running; --stop kills it after; without either it may auto-compact.

[TARGET]

Target: a live session ref, a dead shorthand (auto-resumed), or a directory to spawn in (needs --agent). Omitted: repo's pinned session

[TEXT]…

--agent <AGENT>

--compact-at <COMPACT_AT>

--tokenlimit <TOKENLIMIT>

--no-compact

--keep

--stop

--from <FROM>

--raw

--clear-pending

Drop a stuck request holding this target and exit, sending nothing Prints what it cleared — sender, status, age and the owner pid/host that was waiting on it. Only needed when automatic recovery cannot apply: a record whose owner is dead clears itself on the next request.

--detach

Submit and return a receipt instead of blocking for the reply (headless/worker mode) Returns once the message is delivered (compaction, if any, precedes it), not necessarily instantly. The request is durable: it survives this process exiting, so a tool that kills the waiter cannot lose it. Read the verdict later with tuimote session receipt <receipt>. The target is never auto-stopped (there is no poll loop to stop it after an answer), so --stop is rejected with this.

tuimote session reply

Reply to the request waiting on this pane. (Agent side)

Pass a file path (preferred), inline text, or pipe the reply on stdin.

[PATH]…

--file <FILE>

tuimote session receipt

Read a detached request's verdict by the receipt `session request --detach` returned. (Worker side)

tuimote session receipt <receipt> [--wait SECS]

Reads the mailbox record the receipt names and reports its exact state: replied (with the reply), still pending, terminal, or that the request was replaced/missing/expired. Read-only — it never clears or replaces the record, so a stale receipt cannot consume a later request. --wait N polls up to N seconds for a terminal state instead of reading once. A peer-owned request whose owner is offline reports owner-unreachable with no local fallback.

<RECEIPT>

The opaque token from a --detach submission

--wait <WAIT>

Poll up to N seconds for a terminal verdict before returning the current state

tuimote session self-compact

Compact your own context, then resume where you left off

Run from inside a session pane, or pass --session.

[TEXT]…

--session <SESSION>

tuimote session summary

Write or deliver a single-session summary. [experimental]

tuimote session summary request

Generate a session's summary headlessly from its transcript

Runs the summary headless runner server-side — the session is never resumed and no pane is tasked, so a dormant session works the same as a live one. --archive stops and archives it once the summary lands.

[SLUG]

Session shorthand, or use --agent/--session

--agent <AGENT>

--session <SESSION>

--cwd <CWD>

--archive

tuimote session summary get

Print a session's stored summary

[SLUG]

Session shorthand, or use --agent/--session

--agent <AGENT>

--session <SESSION>

tuimote session summary deliver

Record a summary you generated. (Agent side)

--session <shorthand> alone is enough; the other flags cover dead-session delivery.

[TEXT]…

--session <SESSION>

--agent <AGENT>

--cwd <CWD>

--tmux <TMUX>

--archive

--file <FILE>

tuimote session commit-hook

Record commit → session attribution. (Called by the post-commit hook.)

Reads the current session identity and the just-committed SHA, then writes a .tuimote/commits/<prefix>/<sha>.json record. Silent on failure (a hook must never block a commit).

tuimote session issue-hook

Record issue → session attribution. (Called by the forge shim.)

Reads the issue out of the forge's argv — or, for a freshly created one, out of the bytes it printed — and appends an event to .tuimote/issues/<host>__<owner>__<repo>.jsonl. Silent on failure: it runs after the forge write already landed.

[ARGV]…

The wrapped binary and its arguments

--cwd <CWD>

The directory the forge command ran in

--stdout <STDOUT>

File holding the forge's captured stdout

tuimote session issue-ledger

Read a repo's issue attribution record, as JSON

One object per issue the record knows about, keyed by the forge host it was filed on: who opened it, the last state flip, the last edit, and one entry per attributed comment. Local disk only — the Issues panel reads it through the owning peer, since the record lives where the agent ran.

--cwd <CWD>

The repo to read. Defaults to the current directory

tuimote session unlock

Clear a blocked commit with the password the pre-commit gate printed

The unlock applies to the NEXT commit in this repo and only that one, and expires shortly. Chain your commit onto it:

tuimote session unlock "<password>" && git commit -m "…"

<PASSWORD>

The password from the gate message

--cwd <CWD>

tuimote session blame

Show session attribution for a commit or file

tuimote session blame <sha>          — attribution for one commit tuimote session blame <file>[:<L>-<L>] — per-line session map

Maps commits (or file lines via git blame) to the tuimote sessions that produced them: shorthand, harness, task, and timestamp.

<TARGET>

A commit SHA, or a file path (optionally with :L-L line range)

--json

Emit raw JSON instead of the human table

tuimote session attribute

Manually set, correct, or clear a commit's session attribution

tuimote session attribute <sha> --shorthand <sh>  — a running session tuimote session attribute <sha> --session <id>    — by session id tuimote session attribute <sha> --agent <name>    — harness only tuimote session attribute <sha> --clear           — remove the record

Fills gaps the hook and backfill can't cover (hook not installed, attribution off at commit time, external commit). Writes a source: "manual" record — visibly distinct in blame, never clobbered by a later hook or backfill. The SHA (full or prefix) is resolved against the repo first; a named session's fields are pulled from live state.

<TARGET>

A commit SHA (full or unambiguous prefix)

--shorthand <SHORTHAND>

Attribute to a running session by its shorthand

--session <SESSION>

Attribute to a running session by its session id

--agent <AGENT>

Record a harness name (with or without a session)

--task <TASK>

Optional task string (overrides the session's derived task)

--clear

Remove the attribution record for this commit

--json

Emit raw JSON instead of the human summary

tuimote session dirty

Check whether a running session plausibly owns uncommitted files

<SESSION>

A session shorthand or tmux name

tuimote repo

Per-repo settings: entrance pin, memory, dashboard card, wiring

tuimote repo init

Wire tuimote into a repo and/or install the /tuimote skill

Defaults to --repo on the current directory.

--repo

--global

--cwd <CWD>

--backfill-attribution

Sweep live and archived transcripts after init (requires commitAttribution)

--no-issues

Opt out of the local .tuimote/ issue store (tuimote issue …, the Issues panel's forge-less row) for this repo

tuimote repo backfill-attribution

Reconstruct commit attribution from live and archived transcripts

--cwd <CWD>

--dry-run

Audit candidates and rejects without writing sidecars

tuimote repo customize

Restyle this repo's dashboard card (emoji, icon, name, color)

Only the flags you pass change. --icon-svg takes a file path (read inline; must be <20 KB and script-free).

--emoji <EMOJI>

--icon-svg <ICON_SVG>

--alt-name <ALT_NAME>

--subtitle <SUBTITLE>

--color <COLOR>

--clear

--cwd <CWD>

tuimote repo pin

Pin a session as this repo's entrance point (one per repo)

tuimote repo pin <target>

Pinned sessions skip idle auto-stop and are the default target for send/view/attach/request. No target prints the pin; --clear removes it.

[TARGET]

--clear

Remove this repo's pin

--cwd <CWD>

tuimote repo migrate

Hand this repo's pinned session over to a fresh one (any harness)

tuimote repo migrate --agent codex

The old session writes a handoff, a new one boots reading it and inherits the pin, and the old one is archived.

--agent <AGENT>

Target harness for the successor session (claude/codex/pi/reasonix)

--cwd <CWD>

tuimote repo history

Add a dated entry to this repo's HISTORY.md

Reads from stdin, --file, or positional text.

[TEXT]…

--cwd <CWD>

--file <FILE>

tuimote repo stubs

Generate one-line stubs for all of this repo's sessions

--cwd <CWD>

--agent <AGENT>

--session <SESSION>

Restrict the pass to a single session transcript id

--force

--missing-only

--limit <LIMIT>

--concurrency <CONCURRENCY>

(default: 6)

--model <MODEL>

Run on this model instead of the configured stub runner. The operator may allow only some models here

--timeout <TIMEOUT>

(default: 45)

tuimote repo supercompact

Fold session summaries into repo memory. [experimental]

tuimote repo supercompact start

Run a supercompaction for a repo, in the background

Curates, summarizes the keepers, archives every idle (non-running, non-pinned) session, then folds the summaries into .tuimote/. Both reasoning steps run headlessly — no agent is spawned. Returns at once.

--cwd <CWD>

tuimote repo supercompact deliver

Deliver a hand-written supercompaction report. (Agent side)

Pipe it, or use --file / positional text. --archive also stops and archives every other session in the directory.

[TEXT]…

--cwd <CWD>

--archive

--session <SESSION>

--dry-run

Print what would be archived/stopped without doing it

--file <FILE>

tuimote repo tasks

Event-driven document tasks declared in `.tuimote/tasks.toml`

A task maintains one repo document (SECURITY.md, CODE.md, WORKFLOW.md…) off an event that already happens — a commit landing, a session being summarized or archived.

tuimote repo tasks ls

List the tasks that apply to a repo, and when each last ran

--cwd <CWD>

Repo to read (defaults to the session you're in, then the cwd)

--json

Emit the raw JSON instead of a table

tuimote repo tasks run

Run one task now, ignoring its cooldown. Returns at once

<ID>

Task id from tuimote repo tasks ls

--cwd <CWD>

--sha <SHA>

Commit a diff-input task should review. Defaults to HEAD

--session <SESSION>

Session shorthand the task acts on — the transcript/summary a session-scoped task reads, and the pane a send-mode task goes to

tuimote repo tasks init

Write a starter `.tuimote/tasks.toml` with three commented examples

Refuses to overwrite an existing file unless --force.

--cwd <CWD>

--force

tuimote repo tasks fire

Fire an event, running every task subscribed to it

This is the programmatic trigger: point a harness hook at tuimote repo tasks fire custom:<name> and any task declaring on = ["custom:<name>"] runs. Cooldowns still apply, so a hook that fires on every file write does not become a model call on every file write.

tuimote repo tasks fire custom:schema-touched --file db/schema.sql

<EVENT>

custom:<name>, or post-commit

--cwd <CWD>

--file <FILES>

A path the change touched; repeat for several. Tasks declaring paths are matched against these, and stay quiet when none is given

--payload <PAYLOAD>

Free text the task can read as its payload input

tuimote repo passes

Named refinement passes the Issues panel can run over one issue

A pass is a prompt plus the repo context it wants gathered — code reuse, security risk, simplification, dependency research. Built-ins ship with tuimote; ~/.tuimote/passes.toml overrides them for this machine and .tuimote/passes.toml for this repo.

tuimote repo passes ls

List the passes a repo offers, resolved through all three layers

--cwd <CWD>

Repo to read (defaults to the session you're in, then the cwd)

--json

Emit the raw JSON instead of a table

tuimote repo passes show

Print one pass in full, prompt included

<ID>

Pass id from tuimote repo passes ls

--cwd <CWD>

tuimote repo passes init

Write the built-in passes out as an editable `passes.toml`

Refuses to overwrite an existing file unless --force.

--cwd <CWD>

--global

Write ~/.tuimote/passes.toml (this machine) instead of the repo's

--force

tuimote repo passes set

Add or replace one pass in a `passes.toml`

The whole pass is replaced, never merged field by field — that is what the layering does too, so set on an existing id needs every flag the pass should keep. Start from show if you are editing rather than writing one.

<ID>

Pass id: 1-48 chars of [a-zA-Z0-9_-]

--prompt <PROMPT>

What to look at and what to report. Required for a new pass

--title <TITLE>

Menu label; defaults to the id

--context <CONTEXT>

Context blocks to gather, comma-separated: repo, commits, issues, labels, readme, manifests, issue, comments. --context "" asks for the prompt and nothing else

--dispatch <DISPATCH>

Dispatch modes offered, comma-separated: headless, spawn, send

--model <MODEL>

Provider/model id for headless runs; empty means the passes runner

--tools <TOOLS>

Read-only tools to request, comma-separated: read, grep, find, ls. A request, not a grant — Settings → Agents → Headless is the ceiling

--disabled

Hide the pass without deleting it

--cwd <CWD>

--global

Write this machine's ~/.tuimote/passes.toml instead of the repo's

tuimote repo passes report

Hand a pass's findings back to the Issues panel. (Agent side)

Run this at the end of a refinement pass that was dispatched to your session: a session has no return value, so this is how the report reaches the operator. It lands on the issue's card in the panel, where they post it as a comment or discard it — this command writes nothing to the tracker.

Pass a file path with --file (preferred), inline text, or pipe it on stdin.

<N>

The issue the pass ran on

[TEXT]…

--file <FILE>

--forge <FORGE>

Which tracker (fj, gh), when both have a pass waiting on this issue

--cwd <CWD>

tuimote repo passes rm

Remove a pass from a `passes.toml`

A pass this file owns is deleted. A built-in, or one from a layer below, cannot be subtracted — it is written here as enabled = false instead, so it stays visible and can be switched back on.

<ID>

--cwd <CWD>

--global

Act on ~/.tuimote/passes.toml instead of the repo's

tuimote repo gate

The pre-commit gate. With no subcommand, runs it — this is what `.git/hooks/pre-commit` calls

Exits non-zero only when a block = true task actually decided to stop the commit. Everything else — no tasks, a clean review, an unreachable server, a timeout — exits zero.

tuimote repo gate install

Install the `pre-commit` hook, chaining any hook already there

--cwd <CWD>

--uninstall

Remove it instead, restoring what it displaced

tuimote repo wiring

What each configured harness actually sees in this repo

Rows are resources (context files, skills, slash commands, memory injection), columns are harnesses. With no subcommand, prints the rows that need attention. Reports for peer-owned repos too, read-only.

tuimote repo wiring status

Print the matrix. Only rows needing attention, unless --all

--all

Include the rows that are already fine

--kind <KIND>

Only this kind: context, skill, command, memory

--cwd <CWD>

tuimote repo wiring fix

Run one of the safe fixes, or print what it would change

With no id, lists the fixes and why each is safe to run unattended. Refused for peer-owned repos: the resolver runs there, the disk is there.

[ID]

context:inject, skills:sync-repo, skills:sync-global, memory:create-index, memory:link-claude

--dry-run

Print the plan instead of applying it

--cwd <CWD>

tuimote repo wiring ack

Mark a divergence intentional so it stops asking

Takes a row key (ctx:AGENTS.md) or one column of it (skill:review@pi). The acknowledgement is recorded against the row's current shape and lapses the moment that shape changes.

<KEY>

--clear

Remove the acknowledgement instead

--cwd <CWD>

tuimote repo wiring set

Per-repo overrides: context-file strategy and hidden harness columns

--strategy <STRATEGY>

auto (report bodies that differ), symlink (one source of truth), separate (per-harness files are meant to differ here)

--hide <HIDE>

Drop a harness column from this repo's matrix

--show <SHOW>

Put a hidden harness column back

--cwd <CWD>

tuimote repo panels

Dock panel order and visibility for this repo's switcher

The order is a list of panel ids, so a panel that is removed or re-scoped leaves a dead id behind in every repo that ever ordered it. prune is the non-GUI way to clear those out.

tuimote repo panels ls

Show the switcher order, marking hidden entries and dead ids

A "dead" id is one the repo orders but cannot discover — a panel that was deleted, renamed, or moved to another repo. It never renders.

--cwd <CWD>

Repo to read (defaults to the session you're in, then the cwd)

tuimote repo panels order

Set the order outright, or drop one id from it

tuimote repo panels order --set "artifacts,git,code,shell" tuimote repo panels order --remove bub

An empty --set clears the explicit order (back to natural order).

--set <SET>

Comma-separated panel ids, in switcher order

--remove <REMOVE>

Drop just this id, keeping the rest in place. Repeatable

--cwd <CWD>

tuimote repo panels hide

Hide a panel from this repo's switcher (it stays in the order)

<ID>

--cwd <CWD>

tuimote repo panels show

Unhide a panel

<ID>

--cwd <CWD>

tuimote repo panels prune

Drop every ordered/hidden id the repo can no longer discover

This is the cleanup for a panel that was removed or re-scoped: its id lingers in each repo that ordered it. --all-repos sweeps every repo the server knows about, which is usually what you want after moving one.

--cwd <CWD>

--all-repos

Sweep every known repo instead of just one

--dry-run

Print what would be dropped without writing

tuimote repo templates

Composer templates — the buttons on this repo's template bar

Templates are keyed by repo path, so moving a repo leaves them behind; copy is how they follow it.

tuimote repo templates ls

List a repo's templates (add --global for the cross-repo bar)

--cwd <CWD>

Repo to read (defaults to the session you're in, then the cwd)

--global

Read the global bar instead of this repo's

tuimote repo templates add

Create or update one template, by name

--name <NAME>

Display name — often an emoji. Re-using one overwrites it

--text <TEXT>

The text the button inserts. Reads stdin when omitted

--group <GROUP>

Bundle this template into a named group on the bar

--alias <ALIAS>

Typeable alias for the // dropdown

--cmd

Run the text as a command instead of inserting it

--cwd <CWD>

--global

Write to the global bar instead of this repo's

tuimote repo templates rm

Delete one template by name

--name <NAME>

--cwd <CWD>

--global

tuimote repo templates copy

Copy templates between repos, leaving the source untouched

tuimote repo templates copy --from /old/repo --to /new/repo

Copies every template unless --name is given (repeatable). Existing templates of the same name at the destination are kept unless --overwrite. --dry-run prints the plan.

--from <FROM>

Source repo path

--to <TO>

Destination repo path (defaults to the session you're in)

--name <NAME>

Only this template. Repeatable

--overwrite

Replace destination templates that share a name

--dry-run

Print what would be copied without writing

tuimote repo shell-commands

Shell commands offered in this repo's shell panel

Stored per repo path in the server-owned settings file, so a hand edit to that JSON loses to the next save; copy moves the list to a repo that moved.

tuimote repo shell-commands ls

List this repo's shell commands, in panel order

--cwd <CWD>

Repo to read (defaults to the session you're in, then the cwd)

tuimote repo shell-commands add

Append one command (re-adding an existing one just moves it)

tuimote repo shell-commands add "tuidev lint"

<COMMAND>

The command line, as the panel should offer it

--first

Put it at the top of the list instead of the bottom

--cwd <CWD>

tuimote repo shell-commands rm

Remove one command, by exact text or by its `ls` position

tuimote repo shell-commands rm "tuidev lint" tuimote repo shell-commands rm --index 2

[COMMAND]

Exact command text to drop

--index <INDEX>

1-based position in ls instead of the text

--cwd <CWD>

tuimote repo shell-commands set

Replace the whole list (repeat --command, in panel order)

--command <COMMANDS>

One command. Repeatable; order is kept

--cwd <CWD>

tuimote repo shell-commands clear

Drop every command for this repo

--cwd <CWD>

tuimote repo shell-commands copy

Copy commands from another repo, leaving the source untouched

tuimote repo shell-commands copy --from /old/repo --to /new/repo

Appends the ones the destination does not have; --overwrite replaces the destination list outright. --dry-run prints the plan.

--from <FROM>

Source repo path

--to <TO>

Destination repo path (defaults to the session you're in)

--overwrite

Replace the destination list instead of appending to it

--dry-run

Print what would be written without writing

tuimote repo context

Print this repo's memory playbooks (HISTORY, STATE, NEXT)

state or next prints just that one file (raw, pipeable). To append to HISTORY use repo history instead.

[WHAT]

Which view to print [show | state | next] (default: show)

--cwd <CWD>

Repo to read (defaults to the session you're in, then the cwd)

tuimote config

Global server and request-runner settings

tuimote config profile

Claude account profiles. With no verb, lists them

tuimote config profile ls

List the available profiles and the active one

tuimote config profile switch

Switch the active Claude account profile

<ID>

tuimote config profile add

Add a Claude account profile

--label and --bin are required. --id is derived from the label when omitted; --credentials-command sets an optional refresh command; --home names a private home (see profile home).

--label <LABEL>

--bin <BIN>

--id <ID>

--credentials-command <CREDENTIALS_COMMAND>

--home <HOME>

tuimote config profile home

Point a profile at the private `$HOME` its sessions run under

Only needed when bin is a wrapper that changes $HOME — claude2 gives its account a home of its own so two subscriptions never share a keychain. Transcripts land there, and without this tuimote never reads them: the dashboard shows a stale same-named copy under our home, and commit attribution can neither be recorded nor backfilled.

tuimote config profile home claude-pro /home/claude-pro tuimote config profile home claude-pro --clear

<ID>

[PATH]

Absolute path. Omit with --clear to unset

--clear

tuimote config profile remove

Remove a Claude account profile by its id

<ID>

tuimote config password

Set the web-UI password (how you secure a networked server)

Pass it as an argument, or omit it to be prompted / read it from stdin.

[PASSWORD]

tuimote config ls

List every setting and its current value

--json emits a {key: value} object.

--json

tuimote config get

Print one setting's value (bare; `--pretty`/`--human` emit JSON)

<KEY>

tuimote config set

Change one setting

tuimote config set fontFamily custom

The value is coerced to the key's type (bool, int, or comma-separated list). Only that one field changes.

<KEY>

<VALUE>

tuimote config unset

Clear an optional request default and restore its built-in value

tuimote config unset requestDefaults.warningMessage

<KEY>

tuimote server

Control this tuimote server: usage, logs, restart

tuimote server usage

Show server usage statistics

tuimote server logs

Show the most recent server log lines

--follow

Keep printing new log lines until interrupted

--err

Show the error log instead of standard output

tuimote server restart

Restart the server in place (same binary, no rebuild)

--scope uses the network-scope-staleness recovery path.

--scope

Use the launchd network-scope-staleness recovery restart

tuimote service

Install tuimote as a background OS service

Generates and manages a launchd agent (macOS) or systemd --user unit (Linux). Runs as your user, in $HOME. Use setup for a guided install.

tuimote service install

Write the OS service file (doesn't start it)

Run service load afterwards to start it. Idempotent overwrite.

--bin <BIN>

Path to the tuimote-server binary the service should run. Defaults to the sibling of this CLI binary

tuimote service uninstall

Stop (if running) then remove the OS service file

tuimote service load

Start the service and enable start-at-boot

tuimote service unload

Stop the service (leaves the file in place)

tuimote service status

Report whether the service is installed and running

--json

Emit a machine-readable JSON report instead of the human summary

tuimote auth

Sign-in security: which devices are signed in, and signing them out

tuimote auth sessions

The browsers holding a live sign-in, and how to end one

tuimote auth sessions ls

List signed-in devices: label, last seen, sign-in, expiry, session id

JSON by default; --human prints the table. The device you are reading from is marked only when the caller *is* a browser session — the CLI's own loopback token is not one, so nothing is ever "this device" over the CLI.

tuimote auth sessions revoke

Sign one device out, by session id (the `id` column of `ls`)

Takes effect on that device's next request; nothing else is touched.

<ID>

Session id to revoke

tuimote auth sessions revoke-all

Sign every device out — the "I lost a device" button

The CLI's own credential is not a browser session, so this always ends all of them; --except-current has a device to spare only in the dashboard, where the request carries a session cookie.

--except-current

Keep the session that made this request, if it is one

tuimote auth totp

The authenticator app second factor: what is in force, enrolling one, and the way back in when the phone holding it is gone

tuimote auth totp status

What the second factor is doing: on or off, whether an enrollment is half-finished, and the parameters an authenticator app is held to

Answers from the running server; falls back to ~/.tuimote/config.json when nothing is listening, and says which it read.

tuimote auth totp disable

Turn the second factor off — the recovery path for a lost authenticator

Asks for no password and no code: this command is reached from a shell on the machine running tuimote, which already reads the file the secret is stored in. The secret is erased rather than parked, so turning the factor back on always means a fresh QR and the old one stops working.

Browsers that are already signed in stay signed in — end those with tuimote auth sessions revoke-all.

--yes

Skip the confirmation prompt (for scripts)

tuimote auth totp enroll

Enroll an authenticator app from the terminal, for a host with no browser on it

Prints the otpauth:// URI and the base32 key, then asks for the six digits your app shows. As in the dashboard, enforcement turns on only once a code confirms the enrollment: abandoning this leaves /login exactly as it was.

--confirm <CODE>

Finish the enrollment already in flight with this code, without prompting — the second half of a scripted, two-step enrollment. It never starts a new one: that would replace the secret you just scanned, and the code would be for a secret the server no longer has

tuimote trust

Get this host's certificate authority onto a phone, tablet or laptop

Prints a QR code for the plain-HTTP download address, the literal URL under it, and the install steps per platform — including the second, separate trust toggle iOS requires and does not mention. Re-runnable; tuimote setup prints the same block when it turns HTTPS on.

Reads the config file, so it answers with the server stopped. The CA private key is not printed, served or transmitted by anything.

--json

Emit JSON (address, PEM address, certificate path, reason) instead of the printed code

tuimote peers

Federation: manage the other tuimote servers on your network

Add/remove peers, toggle them, wake a sleeping one (Wake-on-LAN), flip mDNS discovery, and set the shared pairing secret.

tuimote peers ls

List peers and the current discovery config

The bare command prints the human table; --json dumps the raw config.

--json

Emit the raw JSON config instead of the human table

tuimote peers add

Add or update a peer

tuimote peers add host[:port] --cert-fingerprint SHA256 [--label NAME]

<PEER>

Peer address: host or host:port

--label <LABEL>

Friendly dashboard label

--mac <MAC>

Wake-on-LAN MAC (aa:bb:cc:dd:ee:ff, any separator)

--cert-fingerprint <CERT_FINGERPRINT>

SHA-256 fingerprint shown by tuimote peers ls on the peer

--transport <TRANSPORT>

Federation transport (direct or ssh) (default: direct)

--ssh-target <SSH_TARGET>

OpenSSH host/alias used by the managed local forward

tuimote peers remove

Remove a static peer

mDNS-discovered peers reappear on the next browse.

<PEER>

Peer address: host or host:port

tuimote peers toggle

Enable or disable a peer (flips its state)

<PEER>

Peer address: host or host:port

tuimote peers wake

Send a Wake-on-LAN packet to a peer's configured MAC

<PEER>

Peer address: host or host:port

tuimote peers discovery

Turn mDNS discovery on or off

tuimote peers discovery on

<STATE>

on or off

tuimote peers secret

Set the shared pairing secret (never echoed back)

[VALUE]

The secret value (use "" to clear). Omit to only end a grace window

--grace <GRACE>

Bounded key-rollover: keep the previous secret accepted for this long, so a peer that was offline is not split off the moment the new one lands (e.g. 24h, 7d; capped at 30 days). Omit for an INSTANTANEOUS rotation with no grace window

--end-grace

End the grace window now: the previous secret stops being accepted immediately; the current one is unchanged

tuimote artifact

Register files to show in this repo's terminal document reader

Handles markdown, HTML, LaTeX, LilyPond, Mermaid, and images. Run from inside a session pane; the repo defaults to the one you're in.

tuimote artifact add

Register a file to show in the reader

tuimote artifact add PATH [--folder GROUP]

PATH is relative to the repo root. A malformed file is rejected with the linter's error.

<PATH>

--folder <FOLDER>

tuimote artifact remove

Unregister an artifact

<PATH>

tuimote artifact ls

List the registered artifacts

tuimote artifact info

Show one file's metadata — what the reader's info modal reads

Size, kind and the host binary that kind needs, the filesystem's created/modified/changed stamps, the frozen-version span, and the session that registered it. Works on any in-repo file; an unregistered one just reports registered: false.

tuimote artifact info plan.md

<PATH>

tuimote artifact rate

Rate a registered artifact from 1 to 5 stars

The reader's file-info modal shows the same stars, and the Docs list can sort by them or filter to a minimum. STARS of 0 clears the rating back to unrated, which is a different state from one star.

tuimote artifact rate plan.md 4 tuimote artifact rate plan.md 0

<PATH>

<STARS>

1-5 stars, or 0 to clear

tuimote artifact annotations

Show a user's staged notes on an artifact as a rewrite prompt

No path lists every file with staged notes. --clear discards them.

[PATH]

--clear

tuimote artifact update

Roll the live file's current content as the next version snapshot

Freezes the current content as the next version — what the reader's annotate-then-diverge flow does implicitly — and drops any staged notes that targeted the previous version. Reports unchanged when the live content already matches the latest snapshot, and errors when the path is not a registered artifact.

tuimote artifact update plan.md

<PATH>

tuimote artifact show

Open a registered artifact in the attached PWA

Pushes the doc to every device that has this session's terminal open — their Docs reader flips to it with no tap. Run it from inside the session pane; the session it ran in is the one addressed.

Delivery is best effort: a phone that just backgrounded the page has no socket to push into. The command reports how many devices took it and exits 0 either way. An unregistered path is an error — artifact add it first.

tuimote artifact show plan.md

<PATH>

tuimote artifact tabs

Manage reader groups (the reader's tabs)

tuimote artifact tabs ls

List the configured tabs

tuimote artifact tabs add

Create a tab (or add cwds to an existing one of the same name)

<NAME>

Tab name (must not collide with a built-in tab name)

--cwd <CWD>

Member cwd(s). Repeatable

tuimote artifact tabs remove

Remove a tab by name

<NAME>

tuimote panel

Author and check dock panels (the right-edge plugin pages)

verify lints a panel .js file against the rules discovery enforces before a panel is allowed to load.

tuimote panel verify

Lint a panel .js file against the registration rules

tuimote panel verify path/to/panel.js

Exits non-zero if any error-severity rule fails and prints the rule, line, and fix. Warnings and info never block.

<FILE>

Path to the panel .js file

--kind <KIND>

Override the source kind (builtin|user|repo); inferred from the path otherwise. Only repo enforces the sidecar allowlist rules

--json

Emit a machine-readable JSON verdict instead of the human report

tuimote panel ls

List the dock panels available in this repo

Built-in + user-global + repo-local, with their trust/valid state.

tuimote panel trust

Allow this repo's local panels to load

Pass a repo path, or omit it for this session's repo. --revoke withdraws the grant.

[CWD]

--revoke

tuimote shortcut

Dashboard shortcuts: named tiles in the left drawer

A shortcut is a saved deep link — a repo, a running session, a Session Info page, or a repo's dock panel — with a name and an icon. The --session/--sinfo/--panel/--repo flags are the same query params a copied shortcut link carries.

tuimote shortcut ls

List the shortcuts, in the order the drawer shows them

tuimote shortcut add

Create a shortcut

tuimote shortcut add "Tuimote git" --repo tuimote --panel git --emoji 🌿

<NAME>

Shortcut name, shown under the tile

--session <SESSION>

Open a running session, by shorthand (dev-tuimote-1)

--sinfo <SINFO>

Open Session Info, by shorthand or <agent>:<id>

--panel <PANEL>

Open a dock panel by page id (git, issues, …). Needs --repo

--repo <REPO>

Open a repo's card, by slug or cwd

--emoji <EMOJI>

Emoji shown on the shortcut tile

--icon-svg <PATH>

An .svg file on this machine, under 20 KB and script-free; overrides the emoji while it is set

--clear-icon-svg

Drop a previously set custom SVG, going back to the emoji

--color <COLOR>

Tile tint as #rrggbb; empty string clears it

tuimote shortcut edit

Change a shortcut's name, target, or look. Address it by id or name

<SHORTCUT>

Shortcut id or name

--name <NAME>

New name

--session <SESSION>

Open a running session, by shorthand (dev-tuimote-1)

--sinfo <SINFO>

Open Session Info, by shorthand or <agent>:<id>

--panel <PANEL>

Open a dock panel by page id (git, issues, …). Needs --repo

--repo <REPO>

Open a repo's card, by slug or cwd

--emoji <EMOJI>

Emoji shown on the shortcut tile

--icon-svg <PATH>

An .svg file on this machine, under 20 KB and script-free; overrides the emoji while it is set

--clear-icon-svg

Drop a previously set custom SVG, going back to the emoji

--color <COLOR>

Tile tint as #rrggbb; empty string clears it

tuimote shortcut rm

Delete a shortcut, by id or name

<SHORTCUT>

Shortcut id or name

tuimote shortcut move

Move a shortcut to a new 1-based position in the drawer

<SHORTCUT>

Shortcut id or name

<POSITION>

Target position, 1 = first

tuimote shortcut link

Print the URL a shortcut opens — the same link "Copy shortcut link" yields

<SHORTCUT>

Shortcut id or name

tuimote issue

Track issues in this repo's local `.tuimote/` store — no forge needed

The store the Issues panel uses in repos with no forge CLI or remote. Verbs follow gh issue; writes are attributed to the calling session.

tuimote issue list

List issues in this repo's local store

-s, --state <STATE>

open, closed, or all (default: open)

-l, --label <LABEL>

Only issues carrying every named label (repeatable, or comma-separated)

-S, --search <SEARCH>

Free-text search over issue titles and bodies (default: )

--sort <SORT>

Sort field: created, updated, comments, or number [created | updated | comments | number] (default: updated)

--order <ORDER>

Sort direction: asc or desc [asc | desc] (default: desc)

-L, --limit <LIMIT>

Maximum matching issues to return; 0 means all (default: 30)

--json

Raw JSON (the panel's normalized issue shape) instead of a table

--cwd <CWD>

tuimote issue view

Show one issue, comments included

<NUMBER>

--json

--cwd <CWD>

tuimote issue create

File a new issue. Unknown labels are registered with a stable color

-t, --title <TITLE>

-b, --body <BODY>

(default: )

-l, --label <LABEL>

--json

--cwd <CWD>

tuimote issue comment

Comment on an issue

<NUMBER>

-b, --body <BODY>

--cwd <CWD>

tuimote issue edit

Edit title, body, or labels

<NUMBER>

-t, --title <TITLE>

-b, --body <BODY>

--add-label <ADD_LABEL>

--remove-label <REMOVE_LABEL>

--cwd <CWD>

tuimote issue close

Close an issue, optionally with a closing comment

<NUMBER>

-c, --comment <COMMENT>

--cwd <CWD>

tuimote issue reopen

Reopen a closed issue

<NUMBER>

-c, --comment <COMMENT>

--cwd <CWD>

tuimote issue labels

The label registry (seeded with gh's defaults; grows on use)

--json

--cwd <CWD>

tuimote issue count

Open/closed/all totals — the panel's cheap list header count

--json

--cwd <CWD>

tuimote stash

Restore or purge archived and trashed sessions

archive and delete move sessions here. List them, then restore, re-trash, or purge one by its key — or empty the trash.

tuimote stash ls

List archived + trashed sessions

The bare command prints counts and the per-repo breakdown; --all dumps every item, --repo one repo's items, --trash the trash. --json/--pretty emit the raw {archive, trash} object.

--json

Emit the full raw JSON instead of the compact table

--all

Dump every archived and trashed item, one per entry

--repo <REPO>

Dump the items of one repo (path or its tail, e.g. dev/tuimote)

--trash

Dump the trashed items only

tuimote stash restore

Restore a stashed session back to live (archive→live or trash→live), by its key (the `<kind>/<agent>/<rel>` path from `stash ls`)

<ID>

tuimote stash retrash

Move an archived session to trash, by its key

<ID>

tuimote stash purge

Permanently delete one trashed session, by its key

<ID>

tuimote stash empty

Empty the trash (permanently delete every trashed session)

tuimote font

Set a custom terminal/composer font

Upload a woff2/woff/otf/ttf/ttc file, then switch to it with tuimote config set fontFamily custom.

tuimote font upload

Upload a font file (woff2/woff/otf/ttf/ttc) as the custom font

<FILE>

tuimote font delete

Remove the custom font (revert to the system stack)

tuimote font status

Show whether a custom font is set (mime + size)

tuimote skills

List the slash commands an agent offers in a repo

The same set the web composer completes, plus any cross-agent divergence warnings. Defaults the agent and repo to the session you're in.

--agent <AGENT>

Agent id (claude/codex/pi/...). Defaults to this session's agent

--cwd <CWD>

Repo to scan (defaults to the session you're in, then the cwd)

--json

Emit the raw {commands, warnings} JSON

tuimote status

Print a health report for the server, harnesses, and peers

Covers reachability, version, security posture, each harness's availability, and peer/usage status. Read-only. --json for the machine form. Use doctor to also fix what's wrong.

--json

Emit a machine-readable JSON report instead of the human summary

tuimote doctor

Diagnose problems and offer a fix for each

Runs the status checks, then prompts to apply a fix per problem (install hints, config repair, securing a networked host, the OS service, Linux linger). --yes runs unattended; --json just reports.

--yes

Apply every fix without prompting (unattended)

--json

Emit a machine-readable JSON report (suppresses interactive prompts)

tuimote update

Check for a newer release; self-update where safe

Behavior follows the install method: install.sh installs download the signed release, verify it (minisign + SHA-256), swap atomically, and restart the service; Homebrew installs print brew upgrade tuimote && tuimote setup; source builds defer to the dev loop (self-rebuild.sh / tuidev restart).

--check

Report only — never download or swap binaries

--yes

Apply without the confirmation prompt

tuimote setup

One-shot install: set up the service and print your dashboard URL

Runs doctor, installs and starts the OS service, prompts for a password if the host is exposed, then prints the LAN URL. Safe to re-run.

--yes

Run unattended (no prompts)

--verbose

Print every check row of 6/9 CHECKS, not just the exceptions

tuimote secure

Choose how browsers reach this host: HTTPS, or plain HTTP knowingly

Prints what this host does now (bind, recorded choice, listener), then puts the same three-way choice tuimote setup asks at first run — provisioning the certificate, restarting the service and printing the dashboard URL with the scheme that now serves it. Safe to re-run; a choice already on file is reported and only changed if you say so.

--yes

Run unattended: report the state, change nothing (a transport is never picked for you)

tuimote uninstall

Remove tuimote's service and installer-managed files

Keeps global config and state by default. --purge removes ~/.tuimote, but always leaves per-repo .tuimote directories alone.

--purge

Also remove global config and state under ~/.tuimote

tuimote changelog

Show what changed between releases

Prints the release notes shipped with this build, newest release first. Handy around an update:

tuimote changelog --since 1.0.0

--since <VERSION>

Show only releases newer than this version (e.g. your current one)

tuimote completions

Print a shell completion script (zsh, bash, fish, …)

Write it where your shell picks it up, e.g. for zsh:

tuimote completions zsh > ~/.local/share/zsh/site-functions/_tuimote

(and make sure that dir is in $fpath before compinit runs).

<SHELL>

Shell to emit a script for [bash | elvish | fish | powershell | zsh]

tuimote man

Print the man page (roff) to stdout

Write it somewhere man looks, e.g.:

tuimote man > ~/.local/share/man/man1/tuimote.1

tuimote whoami

Show this pane's own session identity (shorthand, cwd, agent)

tuimote chat

Open the global chat session (not tied to any repo)

Spawns or resumes the persistent entrance session from settings, then attaches its tmux. Reach it elsewhere with the target chat.

tuimote dashboard

Serve the browser dashboard from this host, or stop serving it

off makes this host a session backend: the app, /login and the PWA files stop being served, while the API, the terminal sockets and the event stream stay up for federation peers and this CLI — a peer reached through another host's dashboard never needs its own. Applies to the next request, no restart, and survives one.

It shrinks the *unauthenticated* surface; it revokes nothing. A browser already signed in keeps its API access until its session ends (tuimote config password ends them all).

tuimote dashboard off

A bare tuimote dashboard prints the current state.

[STATE]

on or off. Omit to print the current state [on | off]

tuimote search

Search session stubs, summaries, commits, and attributed issues

The bare command prints a summary line and the matching sessions; --json dumps the raw result with evidence blocks.

<QUERY>

--all-repos

Search every known repo instead of the current repo

--cwd <CWD>

Repo path to search. Defaults to the current directory

--limit <LIMIT>

(default: 30)

--json

Emit the raw JSON result