# Use The Oysterun CLI Safely Use this page when you need to run Oysterun command-line operations against a Host, check which Host the CLI will contact, understand when confirmation is required, and recover from common CLI or Host readiness problems. The command shape is: ```text oysterun [options] ``` Existing setup, `show-qr`, and `service:*` commands remain supported. ## Prerequisites - Oysterun is installed on the machine where you run the command. - You know which Host you want to operate. - You have dashboard access or live-session capability for the action you are running. - For service commands, the machine has Node.js 20 or newer available to Oysterun. Starting screen: a terminal on the machine that owns or can reach the target Oysterun Host. ## Start With The Target Host 1. Choose the Host with `--host`, `--origin`, or `--target` when you need an explicit target. 2. If you do not pass a target, check whether `OYSTERUN_HOST_ORIGIN` is set. 3. If neither is set, Oysterun uses the saved CLI profile, then the Host config values `direct_host_url`, `public_base_url`, or `port`. Expected result: the command contacts the intended Oysterun Host. Use explicit target options when more than one Host is available. ## Sign In And Check Auth Use these commands for dashboard CLI access: ```text oysterun auth login oysterun auth status oysterun auth logout ``` Auth token preference is: 1. `--token` 2. `OYSTERUN_DASHBOARD_TOKEN` 3. saved CLI profile token In live Host sessions, installed Oysterun product Skill commands use the Host-provided live-session capability environment when `OYSTERUN_HOST_ORIGIN`, `OYSTERUN_CAPABILITY_TOKEN`, and `OYSTERUN_SESSION_ID` are present. That live-session authority is separate from dashboard login and saved dashboard profiles. Expected result: `oysterun auth status` reports whether dashboard CLI access is available. Raw token values are not printed by normal CLI output. ## Use Service Commands Service commands manage the local Oysterun service installation: ```text oysterun service:start oysterun service:restart oysterun service:restart --restore-sessions oysterun service:install oysterun service:uninstall oysterun uninstall [--confirm DELETE] ``` `oysterun uninstall` is the top-level cleanup command. It removes managed service state, preserves Host config unless the exact `--confirm DELETE` token is supplied, never deletes the Default Browse Root or agent folders, and prints `npm uninstall -g oysterun` as the separate global package removal step. macOS removes launchd state; Linux reports that no launchd service exists while still clearing managed pid/origin runtime state. Expected result: service commands report the local service action they took or why the action was unavailable on the current platform. ## Use Session Commands Common Session commands include: ```text oysterun sessions list oysterun sessions start oysterun sessions status oysterun sessions url oysterun sessions profile get oysterun sessions profile update oysterun sessions rename oysterun sessions stop --confirm oysterun sessions interrupt --confirm oysterun sessions restart --confirm oysterun sessions resume oysterun sessions branch-resume ``` `sessions url` formats the chat URL for the resolved Host and Session without calling a mutating endpoint. Stop, interrupt, and restart require confirmation. Resume commands use persisted Session history; ambiguous history display names fail closed. Expected result: read-only commands print current Session information, while mutating commands either complete with confirmation or refuse the request. ## Use Chat And Loop Commands Common chat and loop commands include: ```text oysterun chat send oysterun chat recent oysterun chat messages oysterun chat messages-around oysterun chat search oysterun chat loop list oysterun chat loop create oysterun chat loop update oysterun chat loop enable oysterun chat loop disable oysterun chat loop delete --confirm ``` `oysterun chat search` uses the same Host-owned Matrix room-search service as the GUI Message Search. It returns one newest-first page with exact Matrix event IDs, bounded previews, directly openable event URLs, and an opaque `next_batch` when more matches exist. The default page size is 20 and `--limit` accepts `1..100`. To continue, repeat the exact Host, Session, query, sender filters, and page size, and pass the immediately preceding `next_batch` unchanged with `--next-batch`. Do not decode, construct, guess, persist for unrelated work, reuse across Sessions, or skip opaque cursors. Stop when enough results have been returned or the cursor is null. The CLI has no implicit all-results crawl. An invalid, expired, or target/query/filter/limit-incompatible cursor fails visibly. Use `--sender ''` when the result set must be restricted to one sender, and repeat that exact value on every continued page. `messages-around` requires a committed Matrix event id. Loop intervals use one positive integer with a unit such as `s`, `m`, `h`, or `d`. Expected result: chat read commands show bounded message results, send commands post to the selected Session, and destructive loop actions require confirmation. ## Use Skill Installation Commands Oysterun can install packaged Oysterun Skills into supported provider skill folders from Session Setup, Session Profile, or the local Route C slash command: ```text /install_oysterun_skill /install_oysterun_skill --update /install_oysterun_skill --overwrite ``` Helper slash commands insert provider-relative Skill references only: ```text /oysterun_sessions_skill /oysterun_session_chat_skill /oysterun_find_context_skill /oysterun_scheduler_skill /oysterun_mail_skill /oysterun_notifications_skill /oysterun_website_skill /oysterun_telegram_skill ``` Expected result: install commands install missing skills or update marker-owned skills only when you explicitly choose update or overwrite. Helper commands do not auto-send, call install endpoints, or mutate provider skill folders. ## P87 Product Skill Modules Product skills are narrow wrappers around the official CLI. Their canonical source is `skills//`; generated `.codex` and Host-asset copies must match it. They do not call Host APIs directly or edit Host databases. - `oysterun-sessions` wraps `oysterun sessions ...` - `oysterun-session-chat` wraps `oysterun chat ...`, including loop commands - `oysterun-find-context` wraps `oysterun chat messages-around ...` - `oysterun-scheduler` wraps `oysterun scheduler ...` - `oysterun-mail` wraps `oysterun mail ...` - `oysterun-notifications` wraps `oysterun notifications ...` - `oysterun-website` wraps `oysterun website ...` - `oysterun-telegram` wraps `oysterun telegram ...` OysterunAgentStore references are external to this source tree. Changing those references requires a separately routed AgentStore update. Mail send defaults to the Host owner recipient and requires the canonical HTML deliverable input. Telegram setup is per Session; the retired global `oysterun telegram feature enable` command is not a normal product operation. ## Output And Safety Rules - Human-readable output is the default. - `--json` returns a structured response with `ok`, `command`, `contract`, `result`, and `error`. - Secret-like fields are redacted in output. - Dangerous mutations require `--confirm`; `--dry-run` reports the planned request without mutating. - Telegram setup is per-session and defaults off. - Critical Host/admin operations remain dashboard/admin APIs and are not exposed through normal live-session runtime capability. ## Recover From CLI Problems If a command does not reach the expected result: 1. Run `oysterun auth status` for dashboard commands. 2. Pass `--host`, `--origin`, or `--target` when the CLI may be using the wrong Host. 3. Add the required `--confirm` token only after you verify the mutation is intentional. 4. Use `--dry-run` before a risky mutation to inspect the planned request. 5. For provider login failures in live chat, follow the visible chat guidance: run `codex /login` for Codex or `claude /login` for Claude from the machine terminal or available remote terminal, then restart the Session. 6. If provider models or provider status are unavailable, retry after the Host finishes loading provider status. 7. If a command still fails, keep the redacted CLI output and current Host URL so support can identify the target and command without exposing secrets.