@meistrari/remy-cli 1.0.0-rc.0 → 1.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +83 -40
  2. package/dist/remy.js +3002 -2983
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,81 +1,120 @@
1
- # Remy CLI
1
+ # Remy
2
2
 
3
- 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.
3
+ Remy is the interactive terminal client for [Coding Agent](https://github.com/meistrari/background-coding-agent). **Run `remy` for normal use.** It signs you in when needed, shows your remote sessions, starts new work, and lets you follow up or finish it—without cloning repositories or running an agent on your computer.
4
4
 
5
- ## Requirements
5
+ Use the other commands only for automation, direct navigation, or configuration.
6
6
 
7
- - Node.js 22 or later
8
- - Access to a Coding Agent deployment
7
+ ## Quick start
9
8
 
10
- ## Install
9
+ Remy requires Bun 1.3.10 or later, access to a Coding Agent deployment, and a browser for first-time Tela device authorization.
11
10
 
12
- Install Remy globally with [mise](https://mise.jdx.dev/):
11
+ Install the published package:
13
12
 
14
13
  ```bash
14
+ # mise
15
+ mise use --global bun@1.3.10
15
16
  mise use --global npm:@meistrari/remy-cli
17
+
18
+ # bun
19
+ bun i -g @meistrari/remy-cli
20
+
21
+ # pnpm
22
+ pnpm i -g @meistrari/remy-cli
16
23
  ```
17
24
 
18
- Or run it without a global installation:
25
+ Then open Remy:
19
26
 
20
27
  ```bash
21
- bunx @meistrari/remy-cli whoami
22
- npx @meistrari/remy-cli whoami
23
- pnpm dlx @meistrari/remy-cli whoami
28
+ remy
24
29
  ```
25
30
 
26
- ## Sign in
31
+ On first use, Remy opens browser-based device authorization, validates your Coding Agent identity, and opens the session dashboard. Later, the same command takes you straight to that dashboard.
27
32
 
28
- `remy login` opens browser-based device authorization. Select a built-in deployment profile with `--env`:
33
+ ## Your everyday workflow
29
34
 
30
- ```bash
31
- remy login --env staging
32
- # or: remy login --env production
33
- ```
35
+ The dashboard is the starting point for all interactive work.
36
+
37
+ ### Start work
38
+
39
+ Press `n` in the dashboard. The new-session flow asks what you want done, selects a GitHub installation when needed, suggests repositories based on your request, and lets you review those suggestions. Before creating the session, choose the agent model and reasoning effort. Remy then opens the session and streams its activity.
40
+
41
+ Use `Tab` while writing the request to complete a local file path. Remy attaches selected paths when you confirm the request. On macOS, `Ctrl+V` adds a PNG from the system clipboard to the request; Remy attaches it on confirmation. Remy uploads files before creating the session.
42
+
43
+ ### Resume or follow up
34
44
 
35
- `REMY_ENVIRONMENT=staging remy login` supplies the same profile when `--env` is omitted.
45
+ Use the arrow keys to select a session in the dashboard and press `Enter` to open it. In a session, type a follow-up and press `Enter` to send it.
36
46
 
37
- For another Coding Agent deployment, provide its endpoints and Tela application IDs:
47
+ | Control | Result |
48
+ | --- | --- |
49
+ | `Esc` | Interrupt the active turn; the session stays open. |
50
+ | `/complete` | Complete an open session after its active turn stops. |
51
+ | `/sessions` | Return to the dashboard. |
52
+ | `/new` | Start another new-session flow. |
53
+ | `/help` | Show session controls. |
54
+ | `/exit` | Leave Remy. |
55
+ | `Ctrl+O` | Expand or collapse activity details. |
56
+
57
+ After a session becomes terminal, press `Esc` to return to the dashboard or `n` to start new work. From the dashboard, press `l` to log out or `q` to quit. `Ctrl+C` exits Remy from the dashboard, wizard, or session view.
58
+
59
+ ## Commands for direct or scripted use
60
+
61
+ The interactive dashboard is the recommended path. Use these commands when a script needs Remy, or when you already know exactly what to open or create.
62
+
63
+ ### Create a session directly
38
64
 
39
65
  ```bash
40
- remy login \
41
- --api-url <agent-api-url> \
42
- --auth-api-url <auth-api-url> \
43
- --requester-application-id <requester-application-uuid> \
44
- --target-application-id <target-application-uuid>
66
+ remy new --repository owner/repository "Add a health check endpoint"
45
67
  ```
46
68
 
47
- 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.
69
+ Repeat `--repository` to select more repositories from the same GitHub installation. If you do not select a repository, supply `--installation <github-installation-id>`. Repeat `--attach <path>` to upload files. `remy new` creates the session from the prompt and flags, then opens it when the terminal is interactive.
48
70
 
49
- 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.
71
+ ### Open a known session
50
72
 
51
- ## Usage
73
+ ```bash
74
+ remy --session <session-id>
75
+ ```
76
+
77
+ ### Automate a session
52
78
 
53
- Confirm the authenticated account:
79
+ `remy new` and `remy --session` use JSON Lines output automatically when standard input or output is not a terminal. Pass `--no-tui` to choose that mode explicitly; `--json` also selects it.
54
80
 
55
81
  ```bash
56
- remy whoami
82
+ remy new --no-tui --repository owner/repository "Add a health check endpoint"
83
+ remy --session <session-id> --json
57
84
  ```
58
85
 
59
- Start an interactive dashboard in a terminal:
86
+ For a newly created session, Remy writes a `created` record, event-name records as they arrive, then a `terminal` record when the submitted turn settles. A completed turn exits with status `0`; another terminal outcome exits with status `1`.
60
87
 
61
- ```bash
62
- remy dashboard
88
+ ```json
89
+ {"type":"created","session_id":"ses_123","state":{"aggregate_status":"open","connection_status":"connected","active_message_id":"smg_123"}}
90
+ {"type":"event","session_id":"ses_123","event":"agent.turn.started"}
91
+ {"type":"terminal","session_id":"ses_123","state":{"aggregate_status":"open","connection_status":"connected","active_message_id":"smg_123","outcome":"completed"}}
63
92
  ```
64
93
 
65
- Create a coding session from the command line, then attach to an existing session later:
94
+ ### Sign in to a different deployment
95
+
96
+ You do not need `remy login` for a normal first run: bare `remy` handles sign-in. Use it to select a deployment profile or change connection settings:
66
97
 
67
98
  ```bash
68
- remy new --repository owner/repository "Add a health check endpoint"
69
- remy --session <session-id>
99
+ remy login --env staging
100
+ # or: remy login --env production
70
101
  ```
71
102
 
72
- `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.
103
+ `REMY_ENVIRONMENT=staging remy login` selects the same profile when `--env` is omitted. With neither a saved configuration nor an explicit profile, `remy login` uses the production profile.
73
104
 
74
- 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.
105
+ For a custom deployment with no saved configuration, provide all four connection values:
75
106
 
76
- 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.
107
+ ```bash
108
+ remy login \
109
+ --api-url <agent-api-url> \
110
+ --auth-api-url <auth-api-url> \
111
+ --requester-application-id <requester-application-uuid> \
112
+ --target-application-id <target-application-uuid>
113
+ ```
114
+
115
+ Remy stores endpoint configuration in `~/.config/remy/config.json` and tokens in `~/.local/state/remy/tokens.json`. Set `XDG_CONFIG_HOME` or `XDG_STATE_HOME` to use different base directories. `remy logout` removes tokens but retains endpoint configuration; pass `--api-url` to require that the supplied URL matches the active API host before logging out.
77
116
 
78
- ## Commands
117
+ ## Complete command reference
79
118
 
80
119
  ```text
81
120
  remy
@@ -88,4 +127,8 @@ remy new [--repository <owner/name> ... --installation <id> --model <name> --rea
88
127
  remy --session <session-id> [--no-tui] [--json]
89
128
  ```
90
129
 
91
- Remy uses only the Coding Agent API; it never clones repositories, reads local Git state, or runs an agent locally.
130
+ Run `remy <command> --help` for flags and command-specific usage. `remy whoami` prints the saved signed-in identity and organization.
131
+
132
+ ## Development and releases
133
+
134
+ This README is copied into the published package. Repository contributors should use [the Remy CLI guide](../../docs/cli.md) for local development, release preparation, and package smoke checks.