@runneth/cli 0.0.0-sha.e9d64d0553e1.production → 0.0.0-sha.f1d89888b053.production

package/README.md

@@ -1,14 +1,18 @@
 # runneth-cli
 
-`runneth-cli` gives local coding agents a fast persistent shell session.
+Runneth brings your AI brain for marketing to the terminal, by [Motion](http://motionapp.com/).
+Use interactive chat, connect to a Runneth VM, or automate conversations and local shell sessions.
+Looking for a web version? [Open Runneth](https://app.runneth.com/).
 
 ```bash
 npx @runneth/cli open
-npx @runneth/cli send 'cd ~/project && pnpm test'
-npx @runneth/cli send 'git status --short'
-npx @runneth/cli oauth login
-npx @runneth/cli ssh
-npx @runneth/cli close
+runneth send 'cd ~/project && pnpm test'
+runneth send 'git status --short'
+runneth oauth login
+runneth chat --workspace <workspace-id>
+runneth conversation create --workspace <workspace-id> --json
+runneth ssh
+runneth close
 ```
 
 ## npm Usage
@@ -26,76 +30,273 @@ Use the npm `beta` channel to try the production build before it is promoted to
 npx @runneth/cli@beta ssh
 ```
 
-The first command starts a small local daemon for the current user. Later `send`
+`runneth open` starts a small local daemon for the current user. Later `send`
 calls reuse the same shell process through a local socket, so `cd`, exported
 environment variables, and other shell state persist between commands.
 
-## Commands
+## Find a command
+
+Run `runneth` or `runneth --help` to see commands grouped by purpose. Each
+description explains what the command does and who it is for. Subcommands are
+nested beneath their parent, with descriptions. Use `runneth help --all` for
+a flat list with full command paths.
 
 ```bash
-runneth-cli open [--name default] [--cwd <path>] [--shell <path>]
-runneth-cli send [--name default] [--timeout-ms 600000] [--stdin] -- <command...>
-runneth-cli status [--name default]
-runneth-cli list
-runneth-cli close [--name default]
-runneth-cli oauth login [--resource <url>] [--client-name "Runneth MCP"] [--scope <scope>] [--no-open]
-runneth-cli oauth status [--resource <url>]
-runneth-cli oauth logout [--resource <url>]
-runneth-cli ssh target add <name> (--host <host> | --ssh-url <url>) [--resource <url>] [--default]
-runneth-cli ssh target import <file>
-runneth-cli ssh target list
-runneth-cli ssh target use <name>
-runneth-cli ssh [--target <name>] [--unique-key | --identity-file <path>] [-- remote-command]
-runneth-cli ssh stdio [--target <name>] [--unique-key | --identity-file <path>]
-runneth-cli skills install [--agent claude|codex|all]
-runneth-cli shutdown
+runneth help --all
+runneth help ssh
+runneth conversation send --help
+runneth --version
 ```
 
+Every command supports `--help` and `-h`. Help runs before sign-in, daemon startup,
+or command execution. `runneth help --json` returns the public command catalog with
+its schema version, package version, command paths, options, required inputs,
+output formats, and effects. Use `runneth help conversation --json` for one group.
+
+| Commands                                 | Purpose                                        | Audience      |
+| ---------------------------------------- | ---------------------------------------------- | ------------- |
+| `chat`                                   | Interactive Runneth conversation               | Human         |
+| `conversation create/send/state/session` | Remote conversation API through JSON or JSONL  | Agent         |
+| `ssh`                                    | Remote shell or command on a Runneth VM        | Both          |
+| `ssh stdio`                              | Persistent remote JSONL control process        | Agent         |
+| `ssh target add/import/list/use/remove`  | Saved VM connections on your computer          | Both          |
+| `oauth login/status/logout`              | Sign-in and locally stored credentials         | Both          |
+| `update`                                 | Install the current CLI update channel         | Both          |
+| `skills install`                         | Runneth instructions for Claude Code and Codex | Human         |
+| `open/send/status/list/close/shutdown`   | Persistent shells on your computer             | Agent or both |
+
+Local shell commands return JSON. They execute on your computer; use `ssh` or
+`ssh stdio` to execute on a Runneth VM. Put shell or remote arguments after `--`,
+including a command's own `--help`:
+
+```bash
+runneth send -- pnpm --help
+runneth ssh --target team -- node --help
+```
+
+Interactive help and chat share a terminal logo. Small windows use a compact
+header, `NO_COLOR=1` disables color, and pipes and `TERM=dumb` use plain text.
+Terminals with hyperlink support can open the Motion and Runneth web links.
+
 Use `--stdin` for multi-line commands:
 
 ```bash
-cat <<'SCRIPT' | runneth-cli send --stdin
+cat <<'SCRIPT' | runneth send --stdin
 cd ~/project
 pnpm check
 SCRIPT
 ```
 
-Runtime files live under `~/.runneth-cli` by default. Set `RUNNETH_CLI_HOME` to
-use a different state directory.
+CLI state files live under `~/.runneth-cli` by default. Set `RUNNETH_CLI_HOME`
+to use a different state directory. Update installation locks use a separate
+per-user location so two CLI homes cannot update the same installation at the
+same time.
+
+## CLI Updates
+
+Each eligible CLI startup launches a small detached worker and immediately
+continues the requested command. The worker verifies the active global npm or
+pnpm installation, then claims at most one registry check every 20 hours for
+that installation, package, and channel. Project-local installations cannot
+claim or suppress that interval. The worker only caches the promoted `latest`
+target; it never installs an update in the background. Installing another CLI
+version does not reset the interval.
+
+The cached result is scoped to the exact installation and installed version
+that was checked. The worker compares registry publication times so a rolled
+back channel or an older target is never presented as an update. A **Do not
+remind me** choice is scoped to the installation, release channel, and target
+version, so it remains effective after another version is installed and a
+concurrent refresh cannot erase it. When a valid cached update is available, an
+interactive `chat` command or interactive `ssh` shell shows three choices:
+**Update now** (selected by default and showing the command that will run),
+**Not now**, and **Do not remind me for this version**. Use the arrow keys or
+`j`/`k` and press Enter. Help, one-shot SSH, other interactive terminal commands,
+non-interactive commands, and machine-readable commands never resolve a cached
+candidate or pause for update input. Eligible commands inspect only local
+cached state in the foreground. They do not run a package manager or contact
+the registry.
+
+Background-check failures do not interrupt the requested command. The detached
+worker writes the latest diagnostic to
+`~/.runneth-cli/update-check-error.log` (or the configured
+`RUNNETH_CLI_HOME`); the next attempt replaces it.
+
+Choosing **Update now** installs the exact version shown in the selector.
+`runneth update` instead follows `latest`, such as
+`pnpm add --global @runneth/cli@latest`. Global npm and pnpm installations
+update through their original package manager and the installation root
+recorded by the background check. The pnpm executable directory is also recorded
+and pinned during replacement, so changing `PNPM_HOME` cannot redirect the
+installed commands. A package-manager failure exits with its
+status. The CLI asks the user to rerun the original command afterward. Source
+checkouts, project-local dependencies, and npm-exec or npx invocations are not
+modified. For npx, rerun with `npx @runneth/cli@latest`.
+
+Before the first manual package-manager upgrade that installs the updater, let
+persistent sessions finish, close them, and run `runneth shutdown` with the
+installed CLI in every CLI home or custom socket you use. Older daemons do not
+publish registrations, so this one-time shutdown is required across all homes.
+If you already upgraded with an old daemon running, `close` and `shutdown`
+remain available. Other daemon-backed commands and updates refuse a reachable
+unregistered daemon in the current home until you shut it down.
+
+The updater does not interrupt a running local daemon or its persistent
+sessions. It refuses to change the installation until the user closes those
+sessions and runs `runneth shutdown`. A shared gate prevents normal CLI
+commands from starting another daemon during installation. The next
+daemon-backed command starts from the updated installation.
+
+Daemon registrations and the transition lock live in
+`.runneth-cli-daemon-gates` under the operating-system account home. Changing
+`TMPDIR`, `TEMP`, `TMP`, or `RUNNETH_CLI_HOME` does not select a separate gate.
+
+### Interrupted-update recovery
+
+Before npm or pnpm starts replacing files, the updater reserves
+`replacement.json` under `.runneth-cli-daemon-gates` in the operating-system
+account home. This record blocks new daemon startup and further updates across
+CLI homes and package directories, even after an updater crash or `SIGKILL`
+allows its heartbeat locks to expire. Existing daemons for other installations
+can still be used and shut down. The record has no expiry. An incomplete or
+unreadable record also blocks admission.
+
+The updater removes its own record only after the package-manager child exits.
+If the updater dies first, use this recovery procedure:
+
+1. Restart the computer. This stops orphaned npm/pnpm processes and their install
+   scripts. Keep the replacement record in place during recovery.
+2. Inspect the record at the exact path printed by the CLI. Its `command`, `args`,
+   `installationRoot`, and `packageName` identify the attempted replacement.
+   Run that package-manager installation command directly to repair the same
+   global installation, preserving its prefix or pnpm global directories.
+   If the record is incomplete, identify the affected installation and repair
+   it before continuing; do not infer that no installer ran.
+3. Require a successful install and verify the repaired CLI's `--version` and
+   `--help`. If either fails, keep the record and finish repairing the package.
+4. Remove only the `replacement.json` file at the reported path, then rerun the
+   intended command. Do not remove registration directories or heartbeat locks.
+
+Do not clear the record because it is old or its updater PID no longer exists.
+Those facts cannot prove that package-manager descendants stopped or that the
+installation is complete.
+
+`runneth shutdown` succeeds when the selected daemon is already stopped. It
+does not start a daemon. After the daemon acknowledges shutdown, health-check
+timeouts are retried for up to five seconds while it stops. A shutdown request
+timeout, an expired stop deadline, or a permission or protocol failure remains
+an error.
 
 ## OAuth
 
-`runneth-cli oauth login` performs OAuth protected-resource discovery, dynamic
-client registration as a public MCP-style client, PKCE authorization, and token
-exchange through a local loopback callback.
+`runneth oauth login` performs OAuth protected-resource discovery, PKCE
+authorization, and token exchange through a local loopback callback. By default
+it uses dynamic client registration as a public MCP-style client. Provide
+`--client-id`/`--clientid` and `--client-secret`/`--secret`, or set
+`RUNNETH_OAUTH_CLIENT_ID` and `RUNNETH_OAUTH_CLIENT_SECRET`, to use a
+pre-registered confidential client instead.
 
 ```bash
-runneth-cli oauth login --resource http://localhost:4100/mcp
-runneth-cli oauth status --resource http://localhost:4100/mcp
+runneth oauth login --resource http://localhost:4100/mcp
+RUNNETH_OAUTH_CLIENT_ID=client-id RUNNETH_OAUTH_CLIENT_SECRET=client-secret runneth oauth login --resource http://localhost:4100/mcp
+runneth oauth status --resource http://localhost:4100/mcp
 ```
 
 OAuth credentials are stored under `~/.runneth-cli/oauth` with user-only file
 permissions on Unix-like systems. Commands that need an access token refresh it
 internally when the server issued a refresh token.
 
+## Chat
+
+`runneth chat` starts an interactive terminal conversation against Builder's
+canonical Runneth conversation API. Official environment builds carry the
+correct Builder URL in the package; use `--api` only for local or custom Builder
+deployments.
+
+```bash
+runneth chat --workspace "$MONDRIAN_WORKSPACE_ID"
+```
+
+If no stored OAuth credential exists, chat starts the same browser-based OAuth
+flow as SSH and stores the credential under `~/.runneth-cli/oauth`. Use
+`--token`, `RUNNETH_TOKEN`, `MONDRIAN_TOKEN`, or `BUILDER_AGENT_CHAT_TOKEN` only
+for automation and local API mocks that should bypass OAuth.
+
+Inside the terminal UI, use `/state` to redraw the current conversation and
+`/exit` to quit.
+
+## Conversation Commands
+
+`runneth conversation` is the machine-oriented conversation interface for
+agents and scripts. It uses the same auth, workspace scoping, and conversation
+API as `runneth chat`, but avoids terminal banners and ANSI UI output.
+
+```bash
+runneth conversation create --workspace "$MONDRIAN_WORKSPACE_ID" --title "SSH routine setup" --json
+runneth conversation send --workspace "$MONDRIAN_WORKSPACE_ID" --conversation "$CONVERSATION_ID" --message "Create a routine" --json
+runneth conversation state --workspace "$MONDRIAN_WORKSPACE_ID" --conversation "$CONVERSATION_ID" --json
+```
+
+`send` waits for the assistant response by default. `send` and `state` require an
+explicit `--conversation`; the CLI does not track an implicit active
+conversation for machine commands. State reads advertise Runneth stream V2, so
+the same command can inspect read-only task-origin transcripts.
+
+Long-lived agents can keep one authenticated process open with JSONL over
+stdin/stdout:
+
+```bash
+runneth conversation session --workspace "$MONDRIAN_WORKSPACE_ID" --jsonl
+```
+
+The session `ready` frame reports the resolved client target context, not a
+separate active conversation identity. Authoritative user and conversation
+identity comes from the `conversation` object returned by `create` and `state`.
+
+Typical requests:
+
+```jsonl
+{"id":"1","method":"create","params":{"title":"SSH routine setup"}}
+{"id":"2","method":"send","params":{"conversationId":"11111111-1111-4111-8111-111111111111","text":"Create a routine"}}
+{"id":"3","method":"state","params":{"conversationId":"11111111-1111-4111-8111-111111111111"}}
+{"id":"4","method":"close"}
+```
+
+Typical responses:
+
+```jsonl
+{"type":"ready","ok":true,"protocol":"runneth-conversation-stdio","version":1,"authMode":"mondrian","workspaceId":"65cbcb84095884aaf08dc76a"}
+{"id":"1","type":"created","ok":true,"conversation":{"id":"11111111-1111-4111-8111-111111111111"}}
+{"id":"2","type":"sent","ok":true,"send":{"assistantMessageId":"55555555-5555-4555-8555-555555555555"}}
+{"id":"2","type":"state","ok":true,"state":{"conversation":{"id":"11111111-1111-4111-8111-111111111111"}}}
+{"id":"2","type":"complete","ok":true,"assistantMessage":{"id":"55555555-5555-4555-8555-555555555555","status":"completed"}}
+```
+
 ## SSH
 
-`runneth-cli ssh` uses the stored OAuth credential for the resource. If no
-credential exists yet, it starts the OAuth login flow first. The first SSH
-connection for a resource/app pair generates an ed25519 keypair, sends the
-public key to the Runneth SSH app, writes an isolated OpenSSH config, and then
-starts `ssh` through the app tunnel.
+`runneth ssh` uses the stored OAuth credential for the resource. If no
+credential exists yet, it starts the OAuth login flow first. Pass a conversation
+and workspace to resolve its public SSH app target from Builder, or pass a
+named, host, or URL target directly. The first SSH connection for a resource/app
+pair generates an ed25519 keypair, sends the public key to the Runneth SSH app,
+writes an isolated OpenSSH config, and then starts `ssh` through the app tunnel.
 
 ```bash
-runneth-cli ssh \
+runneth ssh \
+  --conversation 11111111-1111-4111-8111-111111111111 \
+  --workspace 22222222-2222-4222-8222-222222222222 \
   --resource https://projects.motionapp.com/mcp \
-  --host 93c7ca56-debe-4b95-8be2-a873afe72234.app.runneth.com
+  --api https://projects.motionapp.com
 ```
 
 SSH keys, known hosts, and generated config files are stored under
 `~/.runneth-cli/ssh`. The generated OpenSSH config uses an internal
 `ProxyCommand` transport that attaches the OAuth bearer token to the SSH app
-HTTP tunnel.
+tunnel. The CLI reads the target VM's authenticated `/runneth/ssh/api` metadata
+before connecting, independently of app catalog health:
+VMs that advertise `runneth-ssh-v1` use one full-duplex WebSocket, while older
+VMs continue through the HTTPS tunnel. Transport selection is automatic. Capability
+discovery allows 70 seconds for authorization and response delivery.
 
 ### SSH stdio
 
@@ -103,7 +304,7 @@ Use `ssh stdio` when an agent needs to keep one authenticated SSH connection
 open and run multiple commands or remote processes without reconnecting:
 
 ```bash
-runneth-cli ssh stdio --target primary-vm
+runneth ssh stdio --target primary-vm
 ```
 
 The command writes JSONL events to stdout and reads JSONL requests from stdin.

package/dist/build-defaults.d.ts

@@ -1 +1,6 @@
-export declare const resolveBuildDefaultMcpResourceUrl: () => string | undefined;
+//#region src/build-defaults.d.ts
+declare const resolveBuildDefaultMcpResourceUrl: () => string | undefined;
+declare const resolveBuildDefaultMondrianApiUrl: () => string | undefined;
+declare const resolveBuildDefaultRunnethApiUrl: () => string | undefined;
+//#endregion
+export { resolveBuildDefaultMcpResourceUrl, resolveBuildDefaultMondrianApiUrl, resolveBuildDefaultRunnethApiUrl };

package/dist/build-defaults.js

@@ -1,21 +1,36 @@
+//#region src/build-defaults.ts
 const BUILD_DEFAULT_MONDRIAN_API_URL = "https://projects.motionapp.com/";
-const BUILD_DEFAULT_MONDRIAN_API_URL_PLACEHOLDER = "__RUNNETH_CLI_DEFAULT_MONDRIAN_API_URL__";
+const BUILD_DEFAULT_RUNNETH_API_URL = "https://build-be.runneth.com/";
 const appendMcpPath = (url) => {
-    const basePath = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/u, "");
-    url.pathname = `${basePath}/mcp`;
+	url.pathname = `${url.pathname === "/" ? "" : url.pathname.replace(/\/+$/u, "")}/mcp`;
 };
-export const resolveBuildDefaultMcpResourceUrl = () => {
-    const rawApiUrl = BUILD_DEFAULT_MONDRIAN_API_URL.trim();
-    if (rawApiUrl.length === 0 ||
-        rawApiUrl === BUILD_DEFAULT_MONDRIAN_API_URL_PLACEHOLDER) {
-        return undefined;
-    }
-    const url = new URL(rawApiUrl);
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new Error("Build default MONDRIAN_API_URL must use http or https");
-    }
-    url.hash = "";
-    url.search = "";
-    appendMcpPath(url);
-    return url.toString();
+const resolveBuildDefaultMcpResourceUrl = () => {
+	const apiUrl = resolveBuildDefaultMondrianApiUrl();
+	if (apiUrl === void 0) return;
+	const url = new URL(apiUrl);
+	appendMcpPath(url);
+	return url.toString();
 };
+const normalizeBuildDefaultUrl = (input) => {
+	const rawApiUrl = input.value.trim();
+	if (rawApiUrl.length === 0 || rawApiUrl.startsWith("__RUNNETH_CLI_DEFAULT_") && rawApiUrl.endsWith("_API_URL__")) return;
+	const url = new URL(rawApiUrl);
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`Build default ${input.envName} must use http or https`);
+	url.hash = "";
+	url.search = "";
+	return url.toString().replace(/\/+$/u, "");
+};
+const resolveBuildDefaultMondrianApiUrl = () => {
+	return normalizeBuildDefaultUrl({
+		envName: "MONDRIAN_API_URL",
+		value: BUILD_DEFAULT_MONDRIAN_API_URL
+	});
+};
+const resolveBuildDefaultRunnethApiUrl = () => {
+	return normalizeBuildDefaultUrl({
+		envName: "BACKEND_URL",
+		value: BUILD_DEFAULT_RUNNETH_API_URL
+	});
+};
+//#endregion
+export { resolveBuildDefaultMcpResourceUrl, resolveBuildDefaultMondrianApiUrl, resolveBuildDefaultRunnethApiUrl };

package/dist/cli.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env node
-export {};
+export { };