@meistrari/remy-cli 1.0.0-rc.0

package/README.md

@@ -0,0 +1,91 @@
+# Remy CLI
+
+Remy is the terminal client for [Coding Agent](https://github.com/meistrari/background-coding-agent). Use it to sign in, start coding sessions, and follow existing sessions without cloning a repository or running an agent on your machine.
+
+## Requirements
+
+- Node.js 22 or later
+- Access to a Coding Agent deployment
+
+## Install
+
+Install Remy globally with [mise](https://mise.jdx.dev/):
+
+```bash
+mise use --global npm:@meistrari/remy-cli
+```
+
+Or run it without a global installation:
+
+```bash
+bunx @meistrari/remy-cli whoami
+npx @meistrari/remy-cli whoami
+pnpm dlx @meistrari/remy-cli whoami
+```
+
+## Sign in
+
+`remy login` opens browser-based device authorization. Select a built-in deployment profile with `--env`:
+
+```bash
+remy login --env staging
+# or: remy login --env production
+```
+
+`REMY_ENVIRONMENT=staging remy login` supplies the same profile when `--env` is omitted.
+
+For another Coding Agent deployment, provide its endpoints and Tela application IDs:
+
+```bash
+remy login \
+  --api-url <agent-api-url> \
+  --auth-api-url <auth-api-url> \
+  --requester-application-id <requester-application-uuid> \
+  --target-application-id <target-application-uuid>
+```
+
+Remy opens the approval URL in your browser and stores its configuration at `~/.config/remy/config.json` and tokens at `~/.local/state/remy/tokens.json`. Set `XDG_CONFIG_HOME` or `XDG_STATE_HOME` to use different directories. Interrupted local credential switches are recovered before authenticated commands proceed; if Remy cannot safely restore a complete credential pair, it stops instead of sending credentials.
+
+On first use, bare `remy` shows its Remy splash, signs in through the browser, then continues to the dashboard. The splash footer shows the installed package version. The splash begins with `Checking authentication...` and `Load sessions`. If saved credentials have expired or are unavailable, it switches to `Authentication needed`, shows the validated verification URL and browser-continuation status, and waits for approval; press `q`, `Esc`, or `Ctrl+C` to cancel safely. Saved valid credentials show the validated account email, then session loading and a brief `Sessions loaded!` confirmation before the populated dashboard opens. Use `remy login` to select a profile or pass different endpoints explicitly; it uses the same authentication splash and returns after sign-in instead of opening the dashboard.
+
+## Usage
+
+Confirm the authenticated account:
+
+```bash
+remy whoami
+```
+
+Start an interactive dashboard in a terminal:
+
+```bash
+remy dashboard
+```
+
+Create a coding session from the command line, then attach to an existing session later:
+
+```bash
+remy new --repository owner/repository "Add a health check endpoint"
+remy --session <session-id>
+```
+
+`remy new` creates directly from its prompt and flags. In the interactive dashboard, press `n` to open the guided session wizard or `l` to start logout; confirm logout with `y` or cancel with Escape. `/new` opens the wizard from an attached session, and `/logout` starts the same confirmed logout flow there. The wizard gets repository suggestions from the Coding Agent API, then lets you review or change its selection before creating the session.
+
+In a session composer, arrow keys move through wrapped lines and then recall prior human messages. Accepted slash-command and path completions leave the cursor at the completion end, without an added space, so paths can be completed further. `Cmd+V` pastes text normally. On macOS, `Ctrl+V` adds an image from the system clipboard as a temporary-file attachment when the message is sent. When a session ends, its composer becomes a status band: press `Esc` to return to the dashboard or `n` to start a new session.
+
+For scripts, use `--no-tui` or `--json` with `new` or `--session`. Both disable the terminal view and write JSON Lines lifecycle and event output; non-interactive input or output does this automatically.
+
+## Commands
+
+```text
+remy
+remy help | --help | -h
+remy login [--env production|staging] [--api-url <url> --auth-api-url <url> --requester-application-id <uuid> --target-application-id <uuid>]
+remy logout [--api-url <url>]
+remy whoami
+remy dashboard
+remy new [--repository <owner/name> ... --installation <id> --model <name> --reasoning-effort <low|medium|high|xhigh> --attach <path> ... --no-tui --json] <prompt>
+remy --session <session-id> [--no-tui] [--json]
+```
+
+Remy uses only the Coding Agent API; it never clones repositories, reads local Git state, or runs an agent locally.