@indexnetwork/cli 0.17.0-rc.66.1 → 0.29.0-rc.88.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 +194 -70
  2. package/dist/index.js +1001 -1221
  3. package/package.json +5 -5
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Index CLI
2
2
 
3
- Command-line interface for [Index Network](https://index.network). Chat with the AI agent, manage signals, and discover opportunities — all from your terminal.
3
+ Command-line interface for [Index Network](https://index.network). Message your personal agent, manage intents, and discover opportunities — all from your terminal.
4
4
 
5
5
  ## Installation
6
6
 
@@ -12,47 +12,129 @@ npm install -g @indexnetwork/cli
12
12
 
13
13
  Index helps you find the right people—and helps the right people find you—based on what you are actually trying to do, not just a profile headline. The value is grounded intros: suggestions come from communities you share (syndicates, founder groups, firm networks), not from spraying the open web.
14
14
 
15
- The flow below is one complete story—shape a room, invite people, publish an approved signal, let broker agents evaluate in the background, then review a persisted match.
15
+ The flow below is one complete story—create an intent, let agents negotiate in the background, then review a persisted match.
16
16
 
17
17
  ```bash
18
18
  # login + setup
19
19
  index login
20
20
  index profile
21
21
 
22
- # 1. express intent (signals)
22
+ # 1. express an intent
23
23
  index intent create "federated learning collaboration"
24
24
 
25
- # 2. broker agents evaluate approved signals in the background
25
+ # 2. agents negotiate on your intents in the background
26
26
  index negotiation list
27
27
 
28
28
  # 3. wait for persisted opportunities, then review outcomes
29
29
  index opportunity list --status pending
30
30
  index opportunity show <opportunity-id>
31
- index opportunity accept <opportunity-id>
31
+ index opportunity start-chat <opportunity-id>
32
32
  ```
33
33
 
34
34
  Words you will see elsewhere in this doc: **network** = a community you are in; **intent** = your “what I am looking for” post; **opportunity** = a suggested introduction between you and someone else.
35
35
 
36
36
  ## Commands
37
37
 
38
+ ### Command reference
39
+
40
+ Every exposed CLI command is listed below. Add `--json` for machine-readable
41
+ results; `conversation stream --json` emits one event per line. Command-specific
42
+ flags are listed in [Options](#options), and examples follow this reference.
43
+
44
+ | Command | Function |
45
+ | --- | --- |
46
+ | `index help` | Show global help; also available as `index`, `index --help`, or `index -h`. |
47
+ | `index version` | Show the installed version; also available as `index --version` or `index -v`. |
48
+ | `index login [local\|dev\|prod]` | Sign in through the matching browser app and store this device's session. |
49
+ | `index logout` | Revoke and clear the stored device session. |
50
+ | `index docs [topic]` | Read canonical protocol guidance, optionally narrowed to a topic. |
51
+ | `index agent me` | Read the agent selected to handle your negotiations. |
52
+ | `index profile` | Show your own profile. |
53
+ | `index profile show <user-id>` | Show another user's accessible profile. |
54
+ | `index profile sync` | Research public profile information and return a suggested profile without persisting it. |
55
+ | `index profile update` | Save reviewed name, bio, location, or social links. |
56
+ | `index intent list` | List intents, with optional archived, text-query, and result-limit filters. |
57
+ | `index intent show <id>` | Show one intent. |
58
+ | `index intent prepare <text>` | Prepare a draft, optionally answering recovery prompts; returns an admission receipt when ready. |
59
+ | `index intent create <text>` | Create an intent, optionally using the preparation receipt. |
60
+ | `index intent update <id> <text>` | Update and reprocess an intent's description. |
61
+ | `index intent archive <id>` | Archive an intent so it stops participating in discovery. |
62
+ | `index intent pause <id>` / `resume <id>` | Pause or resume its agent without archiving. |
63
+ | `index intent networks <id>` | List the networks an intent is shared in. |
64
+ | `index intent add-to-network <id> <network-id>` | Share an intent in a network. |
65
+ | `index intent remove-from-network <id> <network-id>` | Stop sharing an intent in a network. |
66
+ | `index negotiation list` | List negotiations, optionally filtered by intent or open/settled state. |
67
+ | `index negotiation show <opportunity-id>` | Read the negotiation's turns, current state, and available actions. |
68
+ | `index negotiation turn <opportunity-id> --action <action> --message <text> --expected-turn-count <n>` | Submit one `propose`, `counter`, `accept`, or `decline` turn against the observed turn count. |
69
+ | `index opportunity list` | List persisted opportunities, with optional status and result-limit filters. |
70
+ | `index opportunity show <id>` | Show an opportunity's presentation and participants. |
71
+ | `index opportunity accept <id>` | Request acceptance through the server's owner-approval flow. |
72
+ | `index opportunity reject <id>` | Reject an opportunity. |
73
+ | `index opportunity start-chat <id>` | Enter the counterpart chat through the opportunity's consent flow. |
74
+ | `index network list` | List your networks. |
75
+ | `index network discover` | Find public networks you can join. |
76
+ | `index network requests` / `request-update` / `request-dismiss` | Review or revise your early-access creation requests. |
77
+ | `index network create <title>` | Create a network when eligible, or submit an early-access creation request. |
78
+ | `index network show <id>` | Show a network and its members. |
79
+ | `index network update <id> [--title <text>] [--prompt <text>]` | Change a network's title or description. |
80
+ | `index network delete <id>` | Delete a network you own. |
81
+ | `index network join <id>` | Join an open network. |
82
+ | `index network leave <id>` | Leave a network. |
83
+ | `index network invite <id> <email>` | Invite a member by email. |
84
+ | `index conversation list` | List your conversations. |
85
+ | `index conversation with <user-id>` | Open or resume a human DM. |
86
+ | `index conversation show <id>` | Read messages; use `agent --intent-id <id>` for the personal agent's scoped messages and pending question. |
87
+ | `index conversation send <id> <text>` | Send a message; for `agent`, supply `--intent-id` and the displayed `--question-id` when answering one question. |
88
+ | `index conversation answer agent` | Submit several question-ID answers in one batch. |
89
+ | `index conversation stream` | Subscribe to conversation, negotiation, opportunity, and intent events over SSE. |
90
+ | `index conversation help` | Show conversation-specific help. |
91
+ | `index onboarding confirm-profile` | Confirm that the owner has reviewed their profile. |
92
+ | `index onboarding complete` | Complete onboarding once profile confirmation and first-intent prerequisites are met. |
93
+ | `index scrape <url>` | Extract text from a URL, optionally guided by an objective. |
94
+ | `index sync` | Read your profile, networks, and intents into `~/.index/context.json`, or stdout with `--json`. |
95
+
38
96
  ### `index login`
39
97
 
40
- Authenticate with Index Network. Opens a browser window that uses your existing session (or a fresh OAuth flow) to call the session-only, fixed-shape CLI credential endpoint, which mints a 90-day API key while keeping CLI requests on the non-web compatibility surface.
98
+ Authenticate with Index Network. Opens a browser window that runs the device authorization grant against your existing session (or a fresh login), then hands this machine a session of its own.
99
+
100
+ ```bash
101
+ index login local # http://localhost:3001 API + http://localhost:3000 web app
102
+ index login dev # https://protocol.dev.index.network API + https://dev.index.network web app
103
+ index login prod # Production (also the default on first login)
104
+ index login --api-url <url> # Custom API; matching web origin is inferred
105
+ index login --api-url <url> --app-url <url> # Override both origins
106
+ ```
107
+
108
+ Credentials are stored in `~/.index/credentials.json`; the latest login replaces the previous target and its session. Without a target, login reuses the stored API origin (or production on first use). The local web app must be running on port 3000 and the API on 3001; the dev web app must be configured to authenticate against the dev protocol service. Browser login explicitly requests protocol v2 and binds the loopback callback with a one-time state. Only a short-lived device code travels through the redirect; the CLI exchanges it at `/api/auth/device/token` for its own session token and sends that as `Authorization: Bearer`. There is no approval prompt, because the web page mints and approves the code itself — no code from anywhere else can enter the grant. A re-login revokes the session it replaces, so logins do not pile up.
109
+
110
+ For noninteractive calls, set exactly one credential:
41
111
 
42
112
  ```bash
43
- index login # Browser-based auth
44
- index login --api-url <url> # Custom server URL
113
+ export INDEX_API_URL='https://protocol.index.network'
114
+ export INDEX_API_KEY='<api-key>'
115
+ index --api-url "$INDEX_API_URL" intent list --json
45
116
  ```
46
117
 
47
- Credentials are stored in `~/.index/credentials.json`. Current browser login explicitly requests protocol v2, binds the loopback callback with a one-time state, and stores both the API-key secret and its exact revocation ID. It sends the key with `x-api-key`. Re-login stores the successful replacement first, then calls the constrained CLI revocation endpoint with the replacement as caller plus the captured previous raw secret and exact row ID; cleanup failures leave the new login usable but print a warning directing the user to remove the prior key in web settings.
118
+ `INDEX_SESSION_TOKEN` uses Bearer authentication; `INDEX_API_KEY` uses `x-api-key`.
119
+ Setting both fails. Environment credentials take precedence over stored browser
120
+ login. The API origin resolves from `--api-url`, then `INDEX_API_URL`, then the
121
+ stored credential URL, then `https://protocol.index.network`. Integrations pass
122
+ the origin explicitly. Agent management and other session-only operations still require a session.
48
123
 
49
- **Rolling deploy order:** v2 clients require the v2 web bridge and intentionally reject callbacks from older web deployments that cannot return the bound state. On dev, this CLI is an RC: wait for both the API and web deployments to succeed before testing v2 login. Do not relax state validation to make a new CLI work against old web.
124
+ ### `index docs` and `index agent`
50
125
 
51
- The v1 login contract (`session_token` callback, Bearer API-key fallback, `--token` manual flow) is removed. Released v1 binaries and legacy `credentials.json` files without a key ID are treated as signed out; upgrade and run `index login`.
126
+ ```bash
127
+ index docs # Summary plus the list of topics
128
+ index docs workflows --json
129
+ index agent me --json
130
+ ```
131
+
132
+ Topics are `identity-context`, `signals`, `communities-networks`,
133
+ `opportunities`, `negotiations`, and `workflows`. An unknown topic exits nonzero.
52
134
 
53
135
  ### `index logout`
54
136
 
55
- Revoke the exact stored CLI API key through `POST /api/auth/cli-credential/revoke`, proving both the active `x-api-key` caller and strict `{keyId,targetKey}` self target, then clear local credentials. If server revocation succeeds but local cleanup fails, logout exits nonzero and asks you to remove the local file manually. The released v1 CLI can only remove its credential locally because it did not store a server key ID; its temporary server key expires after 90 days. Legacy API-key credentials without a revocation ID are retained by the new CLI with a non-success warning that directs you to remove the old key in web settings first rather than implying another login revokes it.
137
+ Revoke this machine's session server-side, then clear the local credential file. A session can revoke itself, so sign-out takes effect immediately without needing your browser. If the server cannot be reached the local file is still cleared, and logout tells you to revoke the device in Index web settings. If local cleanup fails, logout exits nonzero and asks you to remove the file manually.
56
138
 
57
139
  ```bash
58
140
  index logout
@@ -60,46 +142,68 @@ index logout
60
142
 
61
143
  ### `index intent`
62
144
 
63
- Manage your signals (intents). Create signals from natural language, list active signals, view details, and archive signals you no longer need.
145
+ Manage your intents. Create intents from natural language, list active intents, view details, and archive intents you no longer need.
64
146
 
65
147
  ```bash
66
- index intent list # List active signals
67
- index intent list --archived # Include archived signals
148
+ index intent list # List active intents
149
+ index intent list --archived # Include archived intents
68
150
  index intent list --limit 5 # Limit to 5 results
69
- index intent show <id> # Show full signal details
70
- index intent create "Looking for a CTO" # Create from natural language
71
- index intent update <id> "revised text" # Update a signal (runs full pipeline)
72
- index intent archive <id> # Archive a signal
73
- index intent link <id> <network-id> # Link a signal to a network
74
- index intent unlink <id> <network-id> # Unlink a signal from a network
151
+ index intent list --query "CTO" # Match description and summary text
152
+ index intent show <id> # Show full intent details
153
+ index intent prepare "Looking for a CTO" # Read feedback / recovery prompts and receipt
154
+ index intent prepare "Looking for a CTO" --answer 'Prompt label=My answer'
155
+ index intent create "<returned payload>" --receipt '<returned preparationReceipt>'
156
+ index intent pause <id> # Hold the agent without archiving
157
+ index intent resume <id> # Start it again
158
+ index intent update <id> "revised text" # Update an intent (runs full pipeline)
159
+ index intent archive <id> # Archive an intent
160
+ index intent networks <id> # List the networks an intent is shared in
161
+ index intent add-to-network <id> <network-id> # Add an intent to a network
162
+ index intent remove-from-network <id> <network-id> # Remove an intent from a network
75
163
  ```
76
164
 
165
+ Preparation returns `needs_revision` with recovery field labels or `ready` with a
166
+ `payload` and `preparationReceipt`. Use the exact returned payload with its receipt
167
+ in `create`; `--answer` pairs the displayed recovery **label** with your response.
168
+ You can also create directly: the server prepares the description and rejects an
169
+ unadmitted draft. A new intent is shared in every network you belong to. Narrow it afterwards with
170
+ `remove-from-network`, or widen an existing one with `add-to-network`.
171
+
77
172
  ### `index negotiation`
78
173
 
79
- Inspect agent negotiations — the autonomous turn-by-turn exchanges between broker agents that evaluate whether an opportunity exists.
174
+ Read current negotiations and submit structured turns using full opportunity IDs.
80
175
 
81
176
  ```bash
82
- index negotiation list # List your agent's negotiations
83
- index negotiation list --limit 10 # Limit results
84
- index negotiation list --since 1d # Negotiations from the last 24 hours
85
- index negotiation list --since 2026-04-01 # Since a specific date
86
- index negotiation show <id> # Show turn-by-turn details (accepts short ID)
177
+ index negotiation list [--intent-id <id>] [--state open|settled]
178
+ index negotiation show <opportunity-id> --json
179
+ index negotiation turn <opportunity-id> --action propose --message "..." --expected-turn-count 0 --json
87
180
  ```
88
181
 
182
+ Actions are `propose`, `counter`, `accept`, and `decline`. Read the detail's
183
+ `protocol.availableActions` and current `turnCount` before submitting. The
184
+ server enforces eligibility and stale-count protection. The CLI preserves all
185
+ turns and protocol guidance and never retries a rejected or uncertain write.
186
+ Agreement between agents remains separate from the owner's opportunity approval.
187
+ `--limit`, `--since`, and `--status` are unsupported negotiation filters.
188
+
89
189
  ### `index opportunity`
90
190
 
91
191
  Browse and manage discovered opportunities.
92
192
 
93
193
  ```bash
94
194
  index opportunity list # List all opportunities
95
- index opportunity list --status pending # Filter by status
195
+ index opportunity list --status pending # Filter by one status
196
+ index opportunity list --intent-id <id> --statuses negotiating,pending,accepted,expired
96
197
  index opportunity list --limit 5 # Limit results
97
198
  index opportunity show <id> # Show full details
98
199
  index opportunity accept <id> # Accept an opportunity
99
200
  index opportunity reject <id> # Reject an opportunity
201
+ index opportunity start-chat <id> # Open its human chat (pending/accepted)
100
202
  ```
101
203
 
102
- Status values: `pending`, `accepted`, `rejected`, `expired`.
204
+ `--status` accepts one of `pending`, `accepted`, `rejected`, `expired`;
205
+ `--statuses` accepts a comma-separated radar selection including `negotiating`.
206
+ The intent-scoped radar uses `--intent-id <id>`.
103
207
 
104
208
  ### `index network`
105
209
 
@@ -107,6 +211,10 @@ Manage networks (communities). Network creation is direct for eligible staff; ot
107
211
 
108
212
  ```bash
109
213
  index network list # List your networks
214
+ index network discover # Find public networks
215
+ index network requests # View your creation requests
216
+ index network request-update <id> --title "New Name" --prompt "Purpose"
217
+ index network request-dismiss <id>
110
218
  index network create "My Network" # Create directly when eligible; otherwise submit an early-access request
111
219
  index network create "AI" --prompt "AI researchers" # Create or request with a description
112
220
  index network show <id> # Show details and members
@@ -119,45 +227,53 @@ index network invite <id> user@email # Invite directly by email
119
227
 
120
228
  ### `index conversation`
121
229
 
122
- Unified conversation command for AI agent chat and human-to-human messaging. Supports streaming responses, inline markdown formatting, tool call indicators, and special blocks (signal proposals, opportunities).
230
+ Read and message the personal agent within an intent, or use human DMs.
123
231
 
124
232
  ```bash
125
- index conversation # Interactive AI chat REPL
126
- index conversation "find me collaborators" # One-shot message to AI agent
127
- index conversation --session <id> # Resume an AI chat session
128
- index conversation sessions # List AI chat sessions
129
- index conversation list # List all conversations (H2A + H2H)
130
- index conversation with <user-id> # Open or resume a DM
131
- index conversation show <id> # Show messages
132
- index conversation send <id> <msg> # Send a message
133
- index conversation stream # Real-time SSE stream
233
+ index conversation show agent --intent-id <id> --json
234
+ index conversation send agent "..." --intent-id <id> --json
235
+ index conversation send agent "..." --intent-id <id> --question-id <pending-question-id> --json
236
+ index conversation answer agent --intent-id <id> --answer 'question-id=answer' --answer 'other-id=answer' --json
237
+ index conversation list
238
+ index conversation with <user-id>
239
+ index conversation show <conversation-id> [--limit <n>]
240
+ index conversation send <conversation-id> "..."
241
+ index conversation stream --json
134
242
  ```
135
243
 
136
- ### `index profile`
244
+ Agent reads include availability and the pending question. An answer must carry
245
+ the current question ID and its intent scope; stale refusals are surfaced directly.
246
+ Human messages retain their existing conversation IDs. SSE emits one JSON event
247
+ record per line. There is no local agent runtime or interactive chat session.
137
248
 
138
- View user profiles and synchronously enrich your public identity, social, and avatar data.
249
+ ### `index onboarding`
139
250
 
140
251
  ```bash
141
- index profile # Show your own profile
142
- index profile show <user-id> # Show another user's profile
143
- index profile sync # Enrich your profile now and return the resolved identity
144
- index profile search <query> # Search profiles by name or keyword
145
- index profile create # Generate profile from social links
146
- index profile update <action> [--details <text>] # Update profile (action is the verb-phrase, e.g. "add interests")
252
+ index onboarding confirm-profile --json
253
+ index onboarding complete [--intent-id <id>] --json
147
254
  ```
148
255
 
149
- ### `index contact`
256
+ Confirm a profile only after the owner reviews it. Completion uses the server's
257
+ profile-confirmation and first-intent prerequisites; it does not bypass them.
258
+ For a new account: `profile sync` to see suggested facts, `profile update` to save
259
+ what you approve, `onboarding confirm-profile`, `intent prepare` and `intent create`
260
+ with the returned payload and receipt, then `onboarding complete --intent-id <id>`.
150
261
 
151
- Manage your contacts. Add, list, remove, or import contacts.
262
+ ### `index profile`
263
+
264
+ View user profiles and synchronously enrich your public identity, social, and avatar data.
152
265
 
153
266
  ```bash
154
- index contact list # List your contacts
155
- index contact add user@email # Add a contact by email
156
- index contact add user@email --name "Name" # Add with display name
157
- index contact remove user@email # Remove a contact
158
- index contact import --gmail # Import contacts from Gmail
267
+ index profile # Show your own profile
268
+ index profile show <user-id> # Show another user's profile
269
+ index profile sync # Run public profile research prefill (does not persist)
270
+ index profile update --name "Name" --intro "Bio" --location "City"
271
+ index profile update --social 'website=https://example.com' --social 'github=https://github.com/me'
159
272
  ```
160
273
 
274
+ `--social` replaces the full saved social-link list; include every link you want
275
+ to keep. Profile confirmation and onboarding completion remain explicit commands.
276
+
161
277
  ### `index scrape`
162
278
 
163
279
  Scrape and extract content from a URL.
@@ -169,16 +285,20 @@ index scrape https://example.com --objective "..." # Scrape with focus
169
285
 
170
286
  ### `index sync`
171
287
 
172
- Sync all user context (profile, networks, intents, contacts) to a local file.
288
+ Sync profile, networks, and intents to a local file.
173
289
 
174
290
  ```bash
175
291
  index sync # Sync to ~/.index/context.json
176
292
  index sync --json # Output to stdout as JSON
177
293
  ```
178
294
 
295
+ `--json` emits one parseable result or error on stdout. Progress goes to stderr;
296
+ HTTP failures exit nonzero. Sync fails if any required context read
297
+ fails, without saving partial context.
298
+
179
299
  ## Examples: Reviewing Opportunities
180
300
 
181
- Approved signals are evaluated in the background. `opportunity list` only reviews persisted results; it does not start evaluation.
301
+ Approved intents are evaluated in the background. `opportunity list` only reviews persisted results; it does not start evaluation.
182
302
 
183
303
  ### Review and act
184
304
 
@@ -203,17 +323,25 @@ index opportunity reject <id>
203
323
  | Flag | Short | Description |
204
324
  | -------------------- | ----- | --------------------------------------------------------------- |
205
325
  | `--api-url <url>` | | Override API server (default: `https://protocol.index.network`) |
206
- | `--app-url <url>` | | Override app URL for login (default: `https://index.network`) |
207
- | `--session <id>` | `-s` | Resume a specific chat session |
208
- | `--archived` | | Include archived signals (intent list) |
209
- | `--status <status>` | | Filter opportunities by status |
210
- | `--limit <n>` | | Limit number of results |
211
- | `--since <date>` | | Filter by time: ISO date or duration like `1h`, `2d`, `1w` |
212
- | `--prompt <text>` | `-p` | Network description (for `network create`) |
326
+ | `--app-url <url>` | | Override the web app URL for login (default: inferred from the API origin) |
327
+ | `--archived` | | Include archived intents (intent list) |
328
+ | `--status <status>` | | Filter opportunities by one pending/accepted/rejected/expired status |
329
+ | `--statuses <list>` | | Comma-separated radar stages, including negotiating |
330
+ | `--limit <n>` | | Positive result limit for intent/opportunity lists or conversation messages |
331
+ | `--prompt <text>` | `-p` | Network description (for `network create` and `network update`) |
213
332
  | `--title <text>` | | Network title (for `network update`) |
214
- | `--name <name>` | | Display name (for `contact add`) |
215
- | `--gmail` | | Import from Gmail (for `contact import`) |
216
333
  | `--objective <text>` | | Focus objective (for `scrape`) |
334
+ | `--query <text>` | | Match intent description and summary text (intent list) |
335
+ | `--intent-id <id>` | | Filter negotiations, scope agent conversations, or select onboarding's first intent |
336
+ | `--state <state>` | | Filter negotiations by `open` or `settled` |
337
+ | `--action <action>` | | Required negotiation turn action: `propose`, `counter`, `accept`, or `decline` |
338
+ | `--message <text>` | | Required message for a negotiation turn |
339
+ | `--expected-turn-count <n>` | | Required observed nonnegative integer turn count for a negotiation turn |
340
+ | `--question-id <id>` | | Identify the displayed question when answering the personal agent |
341
+ | `--answer <key=value>` | | Repeat for recovery prompt labels or agent question IDs |
342
+ | `--receipt <token>` | | Preparation receipt for intent creation |
343
+ | `--name`, `--intro`, `--location` | | Profile fields to update |
344
+ | `--social <label=value>` | | Repeat to replace profile social links |
217
345
  | `--json` | | Output raw JSON to stdout |
218
346
  | `--help` | `-h` | Show help |
219
347
  | `--version` | `-v` | Show version |
@@ -223,7 +351,7 @@ index opportunity reject <id>
223
351
 
224
352
  ```bash
225
353
  # Run directly with Bun (no build step)
226
- bun src/main.ts conversation
354
+ bun src/main.ts intent list --json
227
355
 
228
356
  # Build for all platforms
229
357
  bun run build
@@ -231,10 +359,6 @@ bun run build
231
359
  # Build for current platform only (fast dev builds)
232
360
  bun scripts/build.ts --current
233
361
 
234
- # Run tests
235
- bun test
236
-
237
362
  # Dry-run publish
238
363
  bun scripts/publish.ts --dry-run
239
364
  ```
240
-