@evident-ai/cli 3.0.1-dev.28a3007 → 3.0.1-dev.3be0a8d

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 +87 -131
  2. package/dist/index.js +246 -551
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,207 +1,166 @@
1
- # @evident-ai/cli
1
+ # @connected/cli
2
2
 
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.
3
+ Run OpenCode locally and connect it to the Connected platform.
9
4
 
10
5
  ## Installation
11
6
 
12
7
  ```bash
13
- npm install -g @evident-ai/cli
8
+ npm install -g @connected/cli
14
9
  ```
15
10
 
16
- Or run it directly with npx:
11
+ Or run directly with npx:
17
12
 
18
13
  ```bash
19
- npx @evident-ai/cli@latest <command>
14
+ npx @connected/cli <command>
20
15
  ```
21
16
 
22
- The installed binary is named `evident`.
23
-
24
17
  ## Commands
25
18
 
26
- ### `evident login`
19
+ ### `connected login`
27
20
 
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.
21
+ Authenticate with Connected using your browser.
30
22
 
31
23
  ```bash
32
- evident login
24
+ connected login
33
25
  ```
34
26
 
35
27
  Options:
36
28
 
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.
29
+ - `--no-browser` - Don't open the browser automatically (copy the URL manually)
30
+ - `--token` - Use token-based authentication (for CI/CD environments)
40
31
 
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).
32
+ ### `connected logout`
43
33
 
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).
34
+ Remove stored credentials from your machine.
49
35
 
50
36
  ```bash
51
- evident logout
37
+ connected logout
52
38
  ```
53
39
 
54
- Options:
55
-
56
- - `--all` — Remove stored credentials for every endpoint.
57
-
58
- ### `evident whoami`
40
+ ### `connected whoami`
59
41
 
60
- Show the currently authenticated user for the current endpoint.
42
+ Show the currently authenticated user.
61
43
 
62
44
  ```bash
63
- evident whoami
45
+ connected whoami
64
46
  ```
65
47
 
66
- ### `evident run`
48
+ ### `connected tunnel`
67
49
 
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.
50
+ Establish a tunnel from your local OpenCode instance to Connected.
72
51
 
73
52
  ```bash
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
53
+ connected tunnel
82
54
  ```
83
55
 
84
56
  Options:
85
57
 
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).
58
+ - `-s, --sandbox <id>` - Connect to a specific sandbox ID
59
+ - `-p, --port <port>` - OpenCode port (default: 4096)
94
60
 
95
- ## Global flags
61
+ ## Getting Started
96
62
 
97
- These apply to every command and select which backend the CLI talks to. The CLI
98
- targets the **production** Evident platform by default.
63
+ ### 1. Install and run OpenCode locally
99
64
 
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`).
103
-
104
- ## Environment variables
105
-
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.
118
-
119
- ## Getting started
120
-
121
- ### 1. Install and authenticate
65
+ First, install OpenCode and start it in your project directory:
122
66
 
123
67
  ```bash
124
- npm install -g @evident-ai/cli
125
- evident login
68
+ # Install OpenCode
69
+ npm install -g opencode-ai
70
+
71
+ # Start OpenCode server in your project
72
+ cd ~/projects/my-app
73
+ opencode serve --port 4096
126
74
  ```
127
75
 
128
- ### 2. Create an agent
76
+ ### 2. Create a Local Mode sandbox
77
+
78
+ In the Connected web app (https://app.connected.run):
129
79
 
130
- In the Evident web app, create an agent (it runs in local mode). Note its agent
131
- ID.
80
+ 1. Click "New Sandbox"
81
+ 2. Select "Local Mode"
82
+ 3. Click "Create Sandbox"
132
83
 
133
- ### 3. Run it on your machine
84
+ Note the sandbox ID from the URL or dashboard.
134
85
 
135
- From your project directory, start the agent:
86
+ ### 3. Connect via the CLI
136
87
 
137
88
  ```bash
138
- evident run --agent <agent-id>
139
- ```
89
+ # Authenticate (first time only)
90
+ connected login
140
91
 
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.
92
+ # Start the tunnel
93
+ connected tunnel --sandbox <sandbox-id>
94
+ ```
144
95
 
145
- For CI or unattended use, set `EVIDENT_AGENT_KEY` and omit `--agent`:
96
+ The tunnel will connect your local OpenCode to the Connected platform, enabling:
146
97
 
147
- ```bash
148
- EVIDENT_AGENT_KEY=<agent-key> evident run --idle-timeout 30
149
- ```
98
+ - Chat through the web interface
99
+ - WhatsApp and Slack integration
100
+ - Session history and management
150
101
 
151
- ## How it works
102
+ ## How It Works
152
103
 
153
104
  ```
154
105
  +-------------------+ +-------------------+ +-------------------+
155
- | Your machine | | Cloudflare edge | | Evident API |
106
+ | Your Machine | | Cloudflare Edge | | Connected API |
156
107
  | | | | | |
157
- | opencode serve <--+---->| Tunnel relay (DO) |<--->| API worker |
158
- | (127.0.0.1:4096) | | (WebSocket) | | |
108
+ | OpenCode (4096) <-+---->| Tunnel Relay (DO) |<--->| Cloud Run |
159
109
  | | | | | |
160
- | evident run ------+---->| | | Web + Slack |
110
+ | connected tunnel |---->| WebSocket | | Neon DB |
161
111
  +-------------------+ +-------------------+ +-------------------+
162
112
  ```
163
113
 
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.
171
-
172
- See [ADR-0039](../../docs/decisions/0039-reuse-opencode-web-ui.md) and
173
- [`docs/architecture.md`](../../docs/architecture.md) for the full design.
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
174
118
 
175
119
  ## Troubleshooting
176
120
 
177
- ### Not logged in / authentication failed
121
+ ### "OpenCode not found on port 4096"
178
122
 
179
- Re-authenticate:
123
+ Make sure OpenCode is running:
180
124
 
181
125
  ```bash
182
- evident logout
183
- evident login
126
+ opencode serve --port 4096
184
127
  ```
185
128
 
186
- In CI, make sure `EVIDENT_AGENT_KEY` (or `EVIDENT_TOKEN`) is set.
129
+ ### "Authentication failed"
130
+
131
+ Re-authenticate:
187
132
 
188
- ### OpenCode isn't reachable
133
+ ```bash
134
+ connected logout
135
+ connected login
136
+ ```
189
137
 
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.
138
+ ### "Tunnel disconnected"
193
139
 
194
- ### Tunnel disconnected
140
+ The CLI will automatically reconnect. If issues persist:
195
141
 
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`.
142
+ 1. Check your internet connection
143
+ 2. Verify OpenCode is still running
144
+ 3. Try restarting the tunnel
198
145
 
199
146
  ## Configuration
200
147
 
201
- Configuration and credentials are stored under:
148
+ Credentials are stored in:
149
+
150
+ - macOS/Linux: `~/.config/connected/`
151
+ - Windows: `%APPDATA%\connected\`
152
+
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:
202
155
 
203
- - `$XDG_CONFIG_HOME/evident/` if `XDG_CONFIG_HOME` is set
204
- - otherwise `~/.config/evident/`
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`).
159
+
160
+ Equivalent environment variables (take precedence over the flags):
161
+
162
+ - `EVIDENT_API_URL` - Override the API URL
163
+ - `EVIDENT_TUNNEL_URL` - Override the tunnel relay URL
205
164
 
206
165
  ## Development
207
166
 
@@ -212,14 +171,11 @@ pnpm install
212
171
  # Build
213
172
  pnpm build
214
173
 
215
- # Run from source
216
- pnpm dev:run <command>
174
+ # Run locally
175
+ pnpm start <command>
217
176
 
218
177
  # Type check
219
178
  pnpm typecheck
220
-
221
- # Test
222
- pnpm test
223
179
  ```
224
180
 
225
181
  ## License