@evident-ai/cli 3.0.1-dev.284117a → 3.0.1-dev.2950803

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 (4) hide show
  1. package/README.md +131 -87
  2. package/dist/index.js +2221 -259
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,166 +1,207 @@
1
- # @connected/cli
1
+ # @evident-ai/cli
2
2
 
3
- Run OpenCode locally and connect it to the Connected platform.
3
+ Run OpenCode locally and connect it to the [Evident](https://evident.run) platform.
4
+
5
+ The `evident` CLI starts (or attaches to) `opencode serve` on your machine and
6
+ exposes it to Evident over a secure tunnel. Your code, secrets, and tools stay
7
+ local — only the messages you send travel through Evident. Once connected, you
8
+ can reach your agent from the web and from Slack.
4
9
 
5
10
  ## Installation
6
11
 
7
12
  ```bash
8
- npm install -g @connected/cli
13
+ npm install -g @evident-ai/cli
9
14
  ```
10
15
 
11
- Or run directly with npx:
16
+ Or run it directly with npx:
12
17
 
13
18
  ```bash
14
- npx @connected/cli <command>
19
+ npx @evident-ai/cli@latest <command>
15
20
  ```
16
21
 
22
+ The installed binary is named `evident`.
23
+
17
24
  ## Commands
18
25
 
19
- ### `connected login`
26
+ ### `evident login`
20
27
 
21
- Authenticate with Connected using your browser.
28
+ Authenticate with Evident. By default this uses the browser-based device flow
29
+ (ADR-0018): the CLI shows a one-time code and opens your browser to confirm it.
22
30
 
23
31
  ```bash
24
- connected login
32
+ evident login
25
33
  ```
26
34
 
27
35
  Options:
28
36
 
29
- - `--no-browser` - Don't open the browser automatically (copy the URL manually)
30
- - `--token` - Use token-based authentication (for CI/CD environments)
37
+ - `--no-browser` — Don't open the browser automatically (visit the URL manually).
38
+ - `--token` — Use token-based authentication instead of the device flow (for
39
+ CI/CD); paste a token when prompted.
31
40
 
32
- ### `connected logout`
41
+ Sessions are stored per endpoint, so you can stay logged in to more than one
42
+ backend at the same time (e.g. production and a preview environment).
33
43
 
34
- Remove stored credentials from your machine.
44
+ ### `evident logout`
45
+
46
+ Remove stored credentials. By default this signs you out of the current endpoint
47
+ only (the one selected by `--endpoint` / `EVIDENT_API_URL`, otherwise
48
+ production).
35
49
 
36
50
  ```bash
37
- connected logout
51
+ evident logout
38
52
  ```
39
53
 
40
- ### `connected whoami`
54
+ Options:
55
+
56
+ - `--all` — Remove stored credentials for every endpoint.
57
+
58
+ ### `evident whoami`
41
59
 
42
- Show the currently authenticated user.
60
+ Show the currently authenticated user for the current endpoint.
43
61
 
44
62
  ```bash
45
- connected whoami
63
+ evident whoami
46
64
  ```
47
65
 
48
- ### `connected tunnel`
66
+ ### `evident run`
49
67
 
50
- Establish a tunnel from your local OpenCode instance to Connected.
68
+ Connect to Evident and serve your agent. `evident run` authenticates, resolves
69
+ which agent to run, ensures `opencode serve` is running on loopback, opens the
70
+ streaming tunnel (which transparently proxies the agent's web surface), and
71
+ delivers any channel messages (e.g. Slack) to your local OpenCode.
51
72
 
52
73
  ```bash
53
- connected tunnel
74
+ # Interactive: connect a specific agent
75
+ evident run --agent <agent-id>
76
+
77
+ # Drive a single conversation
78
+ evident run --agent <agent-id> --conversation <conversation-id>
79
+
80
+ # CI: exit after 30s with no work
81
+ evident run --agent <agent-id> --idle-timeout 30
54
82
  ```
55
83
 
56
84
  Options:
57
85
 
58
- - `-s, --sandbox <id>` - Connect to a specific sandbox ID
59
- - `-p, --port <port>` - OpenCode port (default: 4096)
86
+ - `-a, --agent [id]` — Agent ID to connect to. Optional when `EVIDENT_AGENT_KEY`
87
+ is set (the agent is then resolved automatically from the key).
88
+ - `-p, --port <port>` — OpenCode port (default: `4096`).
89
+ - `-v, --verbose` — Show detailed request/response information.
90
+ - `-c, --conversation <id>` — Process only this specific conversation.
91
+ - `--idle-timeout <seconds>` — Exit after N seconds with no pending work (useful
92
+ in CI to avoid polling indefinitely).
93
+ - `--json` — Output in JSON format (forces non-interactive mode).
60
94
 
61
- ## Getting Started
95
+ ## Global flags
62
96
 
63
- ### 1. Install and run OpenCode locally
97
+ These apply to every command and select which backend the CLI talks to. The CLI
98
+ targets the **production** Evident platform by default.
64
99
 
65
- First, install OpenCode and start it in your project directory:
100
+ - `--endpoint <url>` — Evident REST API base URL (e.g. `http://localhost:3001`).
101
+ A trailing `/v1` is optional — it's added automatically.
102
+ - `--tunnel <url>` — Tunnel WebSocket URL (e.g. `ws://localhost:8787`).
66
103
 
67
- ```bash
68
- # Install OpenCode
69
- npm install -g opencode-ai
104
+ ## Environment variables
70
105
 
71
- # Start OpenCode server in your project
72
- cd ~/projects/my-app
73
- opencode serve --port 4096
74
- ```
106
+ - `EVIDENT_AGENT_KEY` — An agent key. When set, `evident run` authenticates as
107
+ that agent and resolves the agent ID automatically, so `--agent` is not
108
+ required. Ideal for CI/CD.
109
+ - `EVIDENT_TOKEN` — A user token used for authentication (alternative to a
110
+ keychain login from `evident login`).
111
+ - `EVIDENT_API_URL` — Override the API base URL (equivalent to `--endpoint`).
112
+ - `EVIDENT_TUNNEL_URL` — Override the tunnel relay URL (equivalent to `--tunnel`).
113
+
114
+ Authentication precedence for `run`: `EVIDENT_AGENT_KEY` → `EVIDENT_TOKEN` →
115
+ credentials stored by `evident login`. For the URL flags, an explicit
116
+ `--endpoint` / `--tunnel` flag wins over the matching environment variable, which
117
+ in turn overrides the production default.
75
118
 
76
- ### 2. Create a Local Mode sandbox
119
+ ## Getting started
77
120
 
78
- In the Connected web app (https://app.connected.run):
121
+ ### 1. Install and authenticate
79
122
 
80
- 1. Click "New Sandbox"
81
- 2. Select "Local Mode"
82
- 3. Click "Create Sandbox"
123
+ ```bash
124
+ npm install -g @evident-ai/cli
125
+ evident login
126
+ ```
83
127
 
84
- Note the sandbox ID from the URL or dashboard.
128
+ ### 2. Create an agent
85
129
 
86
- ### 3. Connect via the CLI
130
+ In the Evident web app, create an agent (it runs in local mode). Note its agent
131
+ ID.
87
132
 
88
- ```bash
89
- # Authenticate (first time only)
90
- connected login
133
+ ### 3. Run it on your machine
134
+
135
+ From your project directory, start the agent:
91
136
 
92
- # Start the tunnel
93
- connected tunnel --sandbox <sandbox-id>
137
+ ```bash
138
+ evident run --agent <agent-id>
94
139
  ```
95
140
 
96
- The tunnel will connect your local OpenCode to the Connected platform, enabling:
141
+ `evident run` ensures `opencode serve` is running on `127.0.0.1:4096` (starting
142
+ it if needed) and connects the tunnel. Once connected, the web shows the agent as
143
+ online and you can open its chat.
144
+
145
+ For CI or unattended use, set `EVIDENT_AGENT_KEY` and omit `--agent`:
97
146
 
98
- - Chat through the web interface
99
- - WhatsApp and Slack integration
100
- - Session history and management
147
+ ```bash
148
+ EVIDENT_AGENT_KEY=<agent-key> evident run --idle-timeout 30
149
+ ```
101
150
 
102
- ## How It Works
151
+ ## How it works
103
152
 
104
153
  ```
105
154
  +-------------------+ +-------------------+ +-------------------+
106
- | Your Machine | | Cloudflare Edge | | Connected API |
155
+ | Your machine | | Cloudflare edge | | Evident API |
107
156
  | | | | | |
108
- | OpenCode (4096) <-+---->| Tunnel Relay (DO) |<--->| Cloud Run |
157
+ | opencode serve <--+---->| Tunnel relay (DO) |<--->| API worker |
158
+ | (127.0.0.1:4096) | | (WebSocket) | | |
109
159
  | | | | | |
110
- | connected tunnel |---->| WebSocket | | Neon DB |
160
+ | evident run ------+---->| | | Web + Slack |
111
161
  +-------------------+ +-------------------+ +-------------------+
112
162
  ```
113
163
 
114
- 1. The CLI connects to OpenCode running on localhost
115
- 2. Establishes a WebSocket connection to the tunnel relay
116
- 3. Connected routes messages through the tunnel to your local OpenCode
117
- 4. Responses flow back through the same path
164
+ 1. `evident run` ensures `opencode serve` is listening on loopback
165
+ (`127.0.0.1`).
166
+ 2. It opens an outbound WebSocket to the Evident tunnel relay.
167
+ 3. Evident routes web traffic and channel (e.g. Slack) messages through the
168
+ tunnel to your local OpenCode; responses flow back the same way.
169
+ 4. Only one running copy of an agent is active at a time — starting a second copy
170
+ takes over.
118
171
 
119
- ## Troubleshooting
120
-
121
- ### "OpenCode not found on port 4096"
172
+ See [ADR-0039](../../docs/decisions/0039-reuse-opencode-web-ui.md) and
173
+ [`docs/architecture.md`](../../docs/architecture.md) for the full design.
122
174
 
123
- Make sure OpenCode is running:
124
-
125
- ```bash
126
- opencode serve --port 4096
127
- ```
175
+ ## Troubleshooting
128
176
 
129
- ### "Authentication failed"
177
+ ### Not logged in / authentication failed
130
178
 
131
179
  Re-authenticate:
132
180
 
133
181
  ```bash
134
- connected logout
135
- connected login
182
+ evident logout
183
+ evident login
136
184
  ```
137
185
 
138
- ### "Tunnel disconnected"
139
-
140
- The CLI will automatically reconnect. If issues persist:
141
-
142
- 1. Check your internet connection
143
- 2. Verify OpenCode is still running
144
- 3. Try restarting the tunnel
186
+ In CI, make sure `EVIDENT_AGENT_KEY` (or `EVIDENT_TOKEN`) is set.
145
187
 
146
- ## Configuration
188
+ ### OpenCode isn't reachable
147
189
 
148
- Credentials are stored in:
190
+ `evident run` starts `opencode serve` on the port from `--port` (default `4096`)
191
+ if it isn't already running. If you start it yourself, bind it to `127.0.0.1`
192
+ (loopback IPv4) on that port.
149
193
 
150
- - macOS/Linux: `~/.config/connected/`
151
- - Windows: `%APPDATA%\connected\`
194
+ ### Tunnel disconnected
152
195
 
153
- By default the CLI targets the production Evident platform. To point it at a
154
- different backend (local dev, a preview environment, …), use the global flags:
196
+ The CLI reconnects on its own. If problems persist, check your internet
197
+ connection and that OpenCode is still running, then restart `evident run`.
155
198
 
156
- - `--endpoint <url>` - Evident REST API base URL (e.g. `http://localhost:3001`).
157
- A trailing `/v1` is optional — it's added automatically.
158
- - `--tunnel <url>` - Tunnel WebSocket URL (e.g. `ws://localhost:8787`).
199
+ ## Configuration
159
200
 
160
- Equivalent environment variables (take precedence over the flags):
201
+ Configuration and credentials are stored under:
161
202
 
162
- - `EVIDENT_API_URL` - Override the API URL
163
- - `EVIDENT_TUNNEL_URL` - Override the tunnel relay URL
203
+ - `$XDG_CONFIG_HOME/evident/` if `XDG_CONFIG_HOME` is set
204
+ - otherwise `~/.config/evident/`
164
205
 
165
206
  ## Development
166
207
 
@@ -171,11 +212,14 @@ pnpm install
171
212
  # Build
172
213
  pnpm build
173
214
 
174
- # Run locally
175
- pnpm start <command>
215
+ # Run from source
216
+ pnpm dev:run <command>
176
217
 
177
218
  # Type check
178
219
  pnpm typecheck
220
+
221
+ # Test
222
+ pnpm test
179
223
  ```
180
224
 
181
225
  ## License