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

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 +133 -87
  2. package/dist/index.js +2592 -305
  3. package/dist/index.js.map +1 -1
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,166 +1,209 @@
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
+ - `--log-level <level>` — Log verbosity: `debug | info | warn | error` (default:
90
+ `info`). Env: `EVIDENT_LOG_LEVEL`.
91
+ - `-v, --verbose` — Alias for `--log-level debug` (an explicit `--log-level` wins).
92
+ - `-c, --conversation <id>` — Process only this specific conversation.
93
+ - `--idle-timeout <seconds>` — Exit after N seconds with no pending work (useful
94
+ in CI to avoid polling indefinitely).
95
+ - `--json` — Output in JSON format (forces non-interactive mode).
60
96
 
61
- ## Getting Started
97
+ ## Global flags
62
98
 
63
- ### 1. Install and run OpenCode locally
99
+ These apply to every command and select which backend the CLI talks to. The CLI
100
+ targets the **production** Evident platform by default.
64
101
 
65
- First, install OpenCode and start it in your project directory:
102
+ - `--endpoint <url>` — Evident REST API base URL (e.g. `http://localhost:3001`).
103
+ A trailing `/v1` is optional — it's added automatically.
104
+ - `--tunnel <url>` — Tunnel WebSocket URL (e.g. `ws://localhost:8787`).
66
105
 
67
- ```bash
68
- # Install OpenCode
69
- npm install -g opencode-ai
106
+ ## Environment variables
70
107
 
71
- # Start OpenCode server in your project
72
- cd ~/projects/my-app
73
- opencode serve --port 4096
74
- ```
108
+ - `EVIDENT_AGENT_KEY` — An agent key. When set, `evident run` authenticates as
109
+ that agent and resolves the agent ID automatically, so `--agent` is not
110
+ required. Ideal for CI/CD.
111
+ - `EVIDENT_TOKEN` — A user token used for authentication (alternative to a
112
+ keychain login from `evident login`).
113
+ - `EVIDENT_API_URL` — Override the API base URL (equivalent to `--endpoint`).
114
+ - `EVIDENT_TUNNEL_URL` — Override the tunnel relay URL (equivalent to `--tunnel`).
115
+
116
+ Authentication precedence for `run`: `EVIDENT_AGENT_KEY` → `EVIDENT_TOKEN` →
117
+ credentials stored by `evident login`. For the URL flags, an explicit
118
+ `--endpoint` / `--tunnel` flag wins over the matching environment variable, which
119
+ in turn overrides the production default.
75
120
 
76
- ### 2. Create a Local Mode sandbox
121
+ ## Getting started
77
122
 
78
- In the Connected web app (https://app.connected.run):
123
+ ### 1. Install and authenticate
79
124
 
80
- 1. Click "New Sandbox"
81
- 2. Select "Local Mode"
82
- 3. Click "Create Sandbox"
125
+ ```bash
126
+ npm install -g @evident-ai/cli
127
+ evident login
128
+ ```
83
129
 
84
- Note the sandbox ID from the URL or dashboard.
130
+ ### 2. Create an agent
85
131
 
86
- ### 3. Connect via the CLI
132
+ In the Evident web app, create an agent (it runs in local mode). Note its agent
133
+ ID.
87
134
 
88
- ```bash
89
- # Authenticate (first time only)
90
- connected login
135
+ ### 3. Run it on your machine
136
+
137
+ From your project directory, start the agent:
91
138
 
92
- # Start the tunnel
93
- connected tunnel --sandbox <sandbox-id>
139
+ ```bash
140
+ evident run --agent <agent-id>
94
141
  ```
95
142
 
96
- The tunnel will connect your local OpenCode to the Connected platform, enabling:
143
+ `evident run` ensures `opencode serve` is running on `127.0.0.1:4096` (starting
144
+ it if needed) and connects the tunnel. Once connected, the web shows the agent as
145
+ online and you can open its chat.
146
+
147
+ For CI or unattended use, set `EVIDENT_AGENT_KEY` and omit `--agent`:
97
148
 
98
- - Chat through the web interface
99
- - WhatsApp and Slack integration
100
- - Session history and management
149
+ ```bash
150
+ EVIDENT_AGENT_KEY=<agent-key> evident run --idle-timeout 30
151
+ ```
101
152
 
102
- ## How It Works
153
+ ## How it works
103
154
 
104
155
  ```
105
156
  +-------------------+ +-------------------+ +-------------------+
106
- | Your Machine | | Cloudflare Edge | | Connected API |
157
+ | Your machine | | Cloudflare edge | | Evident API |
107
158
  | | | | | |
108
- | OpenCode (4096) <-+---->| Tunnel Relay (DO) |<--->| Cloud Run |
159
+ | opencode serve <--+---->| Tunnel relay (DO) |<--->| API worker |
160
+ | (127.0.0.1:4096) | | (WebSocket) | | |
109
161
  | | | | | |
110
- | connected tunnel |---->| WebSocket | | Neon DB |
162
+ | evident run ------+---->| | | Web + Slack |
111
163
  +-------------------+ +-------------------+ +-------------------+
112
164
  ```
113
165
 
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
166
+ 1. `evident run` ensures `opencode serve` is listening on loopback
167
+ (`127.0.0.1`).
168
+ 2. It opens an outbound WebSocket to the Evident tunnel relay.
169
+ 3. Evident routes web traffic and channel (e.g. Slack) messages through the
170
+ tunnel to your local OpenCode; responses flow back the same way.
171
+ 4. Only one running copy of an agent is active at a time — starting a second copy
172
+ takes over.
118
173
 
119
- ## Troubleshooting
120
-
121
- ### "OpenCode not found on port 4096"
174
+ See [ADR-0039](../../docs/decisions/0039-reuse-opencode-web-ui.md) and
175
+ [`docs/architecture.md`](../../docs/architecture.md) for the full design.
122
176
 
123
- Make sure OpenCode is running:
124
-
125
- ```bash
126
- opencode serve --port 4096
127
- ```
177
+ ## Troubleshooting
128
178
 
129
- ### "Authentication failed"
179
+ ### Not logged in / authentication failed
130
180
 
131
181
  Re-authenticate:
132
182
 
133
183
  ```bash
134
- connected logout
135
- connected login
184
+ evident logout
185
+ evident login
136
186
  ```
137
187
 
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
188
+ In CI, make sure `EVIDENT_AGENT_KEY` (or `EVIDENT_TOKEN`) is set.
145
189
 
146
- ## Configuration
190
+ ### OpenCode isn't reachable
147
191
 
148
- Credentials are stored in:
192
+ `evident run` starts `opencode serve` on the port from `--port` (default `4096`)
193
+ if it isn't already running. If you start it yourself, bind it to `127.0.0.1`
194
+ (loopback IPv4) on that port.
149
195
 
150
- - macOS/Linux: `~/.config/connected/`
151
- - Windows: `%APPDATA%\connected\`
196
+ ### Tunnel disconnected
152
197
 
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:
198
+ The CLI reconnects on its own. If problems persist, check your internet
199
+ connection and that OpenCode is still running, then restart `evident run`.
155
200
 
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`).
201
+ ## Configuration
159
202
 
160
- Equivalent environment variables (take precedence over the flags):
203
+ Configuration and credentials are stored under:
161
204
 
162
- - `EVIDENT_API_URL` - Override the API URL
163
- - `EVIDENT_TUNNEL_URL` - Override the tunnel relay URL
205
+ - `$XDG_CONFIG_HOME/evident/` if `XDG_CONFIG_HOME` is set
206
+ - otherwise `~/.config/evident/`
164
207
 
165
208
  ## Development
166
209
 
@@ -171,11 +214,14 @@ pnpm install
171
214
  # Build
172
215
  pnpm build
173
216
 
174
- # Run locally
175
- pnpm start <command>
217
+ # Run from source
218
+ pnpm dev:run <command>
176
219
 
177
220
  # Type check
178
221
  pnpm typecheck
222
+
223
+ # Test
224
+ pnpm test
179
225
  ```
180
226
 
181
227
  ## License