Reference
Command line
Every conch command. Having the terminal of the computer Conch runs on is the proof that it's you.
Run these in a terminal on the computer Conch runs on. The installer adds conch to your terminal; in a checkout of the code, type pnpm conch instead. conch help prints the same list, and conch help <command> says more about one.
Getting started
- setup [--domain <name> | --proxy <name> | --tailscale | --local]
- Asks how you’ll reach Conch: at an address of your own (conch.yourname.com), through a tunnel or web server you already run (Cloudflare Tunnel, nginx, Caddy), privately with Tailscale, or only from this computer. For an address, it shows the DNS record to add and waits for it, gets Conch permission to answer on ports 80 and 443 (asking once for your password on Linux), opens this server’s firewall when you say so, and gets a certificate from Let’s Encrypt. Through your own tunnel, it says where to point it, and checks the way in through it. Either way it ends with the link that makes Conch yours. The installer runs it on a server; run it again any time to change your mind. --yes asks nothing.
- address [set <name>|renew|here|off]
- With nothing after it, says where Conch answers, how long its certificate is good for (or which tunnel or web server answers for it) and anything in the way, with the one thing to do about it. Conch renews the certificate by itself. off stops answering there; set changes it, through the same steps as setup, and set <name> --proxy for a name your own tunnel or web server answers at.
address (nothing), statusWhere Conch answers, and its certificate address set <name>Answer at this address (the same steps as setup) address set <name> --proxyAnswer at this address through a tunnel or web server you run address renewRenew the certificate now (behind a proxy: look through it again) address hereTurn on here an address a backup brought from another computer address offStop answering at it - hello
- For a Conch nobody has signed in to yet, often one on a server: prints a one-time link and a QR code. Open it on your own computer to choose Touch ID, Windows Hello or a password. Whoever opens it first owns this Conch, and it works once, for an hour. After conch reset, it’s the way back in.
- open [page] [--link]
- Opens Conch in your default browser as the computer it runs on, as its app does: that browser can then use Conch with sign-in off, and approve devices. --link prints a one-time link instead, for another browser on this computer or one at the end of an SSH tunnel. It works once, for two minutes, and only on this computer.
Signing in
- status
- The same checkup as Settings → Security: each warning in plain words with its fix, then how many devices are signed in, how many access keys exist and whether a device is waiting.
- password [--generate]
- Turns password sign-in on. Asks for a username and a password of at least 15 characters, typed twice; an empty line, or --generate, makes a strong one and shows it once. Every other signed-in device is signed out.
- key [name]
- Makes a key for a script or another device and shows it once. Paste it on the sign-in screen, or send it as an Authorization: Bearer header.
- keys
- Each key’s name, its last characters, its id and when it was last used.
- revoke <id>
- The key stops working at once, and every device signed in with it is signed out.
- pair
- Prints a QR code and a link that sign one device in. It works once, for ten minutes. Sign-in has to be set up first, and the phone has to be able to reach Conch: conch phone gives it a private address, conch setup an address of your own.
- passkeys [remove <id>]
- Lists the passkeys that sign in to Conch, the address each works at, and when each was last used. remove forgets one and signs out what it signed in, but never your last way in. Passkeys are added from Conch itself, on the device that keeps them.
passkeys (nothing)Your passkeys, and where each one works passkeys remove <id>Forget one (never the last way in) - reset
- The way back in: having this terminal is the proof that it’s you. Forgets the password, every access key and every passkey, signs every device out and leaves Conch open to this computer only (on a server, conch hello then makes it yours again). Every browser on this computer opens Conch from your apps once more. Asks you to type “reset” first.
Devices
- devices
- Lists every device that has signed in and any that are waiting. With approval on, a new device waits, even with the right password, until you let it in: here, or from a device that’s already signed in.
devices (nothing), list [--json]What has signed in, and who is waiting devices approve [code] [--yes]Let a waiting device in (asks which, or waits for one) devices reject [code] [--all]Turn a waiting device down devices remove [id] [--yes]Forget a device and sign it out devices rename <id> <name>Give a device a name you’ll recognise devices onNew devices need your approval after signing in devices offAnyone with the password or key gets in again - sign-out-everywhere
- Ends every session at once. Your password and access keys keep working.
Running Conch
- command [on|off]
- The installer does this for you: conch then works in any terminal, without going to Conch’s folder first. It always runs the version of Conch that’s running. When its folder isn’t on your PATH yet, Conch adds one marked line to your shell’s profile; off takes the command and that line away again.
- background [on|off]
- With nothing after it, says whether Always on is on and where Conch is running. on starts Conch at login and moves it to the background now; off stops it starting by itself, and leaves the running Conch alone.
- quit
- Stops the Conch that is answering, in a window or in the background. With Always on, it starts again at the next login or when you open the app.
- shortcut [remove]
- Adds Conch to Applications, the Start menu or the app menu. Opening it starts Conch first when it isn’t running. remove takes it out again.
- tray [on|off]
- Shows a pearl that says whether Conch is running, wears a dot when something needs you, and opens, starts or quits Conch. With nothing after it, says whether it’s showing.
- background after-logout on
- For a computer that stays on. When it needs an administrator, it prints the one command to run. off undoes it.
- phone
- Turns on an encrypted address that only your own devices can reach, through Tailscale, and prints it. When Tailscale is missing, stopped or signed out, it says what to do next.
Your things
- import --from <app> [--dry-run]
- Brings memories, your persona, skills (off until you turn them on) and scheduled jobs (as draft routines) from openclaw or hermes. --dry-run only lists what would come over. Chat bots and keys come over in the app, where you can tick them.
- skills sign <folder>
- Signs a skill folder with your key, so people who trust you see “Verified”, and manages whose signed skills you trust. Your key is locked with this computer’s own key, so it opens here and nowhere else (a passphrase-locked backup carries it to a new computer).
skills sign <folder> [--as name]Sign a skill you share skills keyYour public key, for people who trust you skills key --newA new key, when yours can’t be opened skills trust <key> --as nameTrust a publisher’s key skills trustedWhose skills you trust skills forget <fingerprint>Stop trusting a publisher