@hive3/cli 0.2.1 → 0.4.0

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.
package/README.md CHANGED
@@ -1,130 +1,176 @@
1
- # Hive CLI
1
+ # Hive3 CLI
2
2
 
3
- Installable command-line client for Hive's person-owned public API credentials. The CLI always uses the signed-in person's account key. Communities do not receive API keys; community actions are available only when `hive capabilities` shows a current role for that person.
3
+ Command-line client for the Hive3 public API. The CLI always uses the API key of the account you sign in with. Accounts in Hive3 are unified: a personal profile and a community are the same kind of account, so the CLI can act on your own account and on any account where you currently are owner, admin or moderator. Run `hive3 capabilities` to see which accounts your key can act on and what it may do there. (The API still calls these "communities" and "person" in some field names.)
4
4
 
5
5
  ## Install And Login
6
6
 
7
- ```bash
8
- pnpm --filter @hive3/cli check
9
- hive login
10
- hive whoami
11
- hive capabilities
12
- ```
13
-
14
- The package installs both command names. Use `hive` or `hive3` interchangeably:
7
+ Requires Node.js 20 or newer.
15
8
 
16
9
  ```bash
10
+ npm install --global @hive3/cli
17
11
  hive3 login
18
12
  hive3 whoami
13
+ hive3 capabilities
19
14
  ```
20
15
 
21
- By default, `hive login` opens an approval page where the signed-in user chooses either Read Only or Full Access. Scripted logins can preselect a bundle:
16
+ The command is `hive3`. `hive` also works for compatibility. Check the installed version with `hive3 --version`.
17
+
18
+ Run `hive3 --help` for the command list, or `hive3 <command> --help` (for example `hive3 profile --help`) for the actions and flags of one command. Help never needs a login.
19
+
20
+ By default, `hive3 login` opens an approval page where the signed-in user chooses either Read Only or Full Access. Approve only the code shown in your own terminal. Scripted logins can preselect a bundle:
22
21
 
23
22
  ```bash
24
- hive login --access read
25
- hive login --access full
23
+ hive3 login --access read
24
+ hive3 login --access full
26
25
  ```
27
26
 
28
- The CLI stores credentials in the OS config directory, or `HIVE_CONFIG_HOME` when set. It prints approval URLs, codes, key prefixes, and config paths, but never prints the API key secret after login completion.
27
+ Approving a login requires a Honey Bee (or higher) plan; otherwise the approval page shows "A Honey Bee subscription is required to create API keys." and Approve is disabled. CLI keys last 90 days. If your plan drops below Honey Bee later, the key stays stored but every API call returns a `plan_required` error until the plan is active again; the CLI tells you to upgrade under Settings in the Hive app, and the key works again without a new login.
28
+
29
+ A CLI key reaches every account where its signed-in owner is owner, admin or moderator. To act as a different signed-in user, run `hive3 logout` and log in as that user. `hive3 logout` revokes the current key on the server (`DELETE /account/keys/current`) and removes the local file; if the server is unreachable it still removes the local file and warns you to revoke the key under Settings → Help & feedback → Developer API keys.
30
+
31
+ ### Where credentials live
29
32
 
30
- Useful environment overrides:
33
+ The CLI stores the API key, API URL, key prefix and scopes in a `config.json` file:
31
34
 
32
- - `HIVE_API_URL`: public API base URL, default `https://app.hive3.tech/api/v1`
33
- - `HIVE_APP_URL`: browser approval app URL, default `https://app.hive3.tech`
34
- - `HIVE_CONFIG_HOME`: test/custom config directory
35
+ | Platform | Location |
36
+ |---|---|
37
+ | any, when `HIVE_CONFIG_HOME` is set | `$HIVE_CONFIG_HOME/config.json` |
38
+ | macOS | `~/Library/Application Support/Hive/config.json` |
39
+ | Windows | `%APPDATA%\Hive\config.json` |
40
+ | Linux and others | `$XDG_CONFIG_HOME/hive/config.json`, or `~/.config/hive/config.json` |
41
+
42
+ The directory is created with mode `0700` and the file is written with mode `0600` (owner read/write only) through a randomly named private staging directory and an atomic rename, so no predictable temporary file is ever created, even when `HIVE_CONFIG_HOME` points at a shared directory. An already existing config directory keeps the permissions you gave it. The key is stored in plain text, protected by those file permissions; it is never printed, logged or placed on a command line. `hive3 logout` revokes the key on the server (`DELETE /account/keys/current`) and removes the file.
43
+
44
+ ### Environment variables
45
+
46
+ - `HIVE_API_URL`: public API base URL used by `hive3 login`, default `https://app.hive3.tech/api/v1`.
47
+ - `HIVE_APP_URL`: browser approval app URL used by `hive3 login`, default `https://app.hive3.tech`.
48
+ - `HIVE_CONFIG_HOME`: directory that holds `config.json` (and the update-check cache).
49
+ - `HIVE_NO_UPDATE_CHECK=1`: disable the automatic daily update check.
50
+
51
+ `HIVE_API_URL` and `HIVE_APP_URL` only affect `hive3 login` (the `--api-url` and `--app-url` flags override them). After login every command uses the API URL stored with the key, so changing `HIVE_API_URL` later does not redirect an existing key. To use a different API URL, log in again. Plain `http` is accepted only for `localhost`/loopback addresses.
35
52
 
36
53
  ## Updating
37
54
 
38
- The CLI checks npm for a new stable release at most once every 24 hours during interactive use. If an update is available, it prints a short notice after the command finishes. Update with:
55
+ The CLI checks npm for a newer release at most once every 24 hours during interactive use (not in CI) and prints a short notice after the command finishes. Update with:
56
+
57
+ ```bash
58
+ hive3 update
59
+ ```
60
+
61
+ `hive3 update` looks up the latest version, prints it, and installs exactly that version (`npm install --global @hive3/cli@<version>`), so the version you were shown is the version you get. It runs npm directly with fixed arguments and a strictly validated version, never through a user-controlled shell command; on Windows it runs `npm.cmd` through the shell, which recent Node versions require. Use `hive3 update --check` to check without installing. Integrity checking is npm's: the update only talks to the public npm registry, never sends Hive credentials, and does not add its own signature check.
62
+
63
+ ## Agent skill
64
+
65
+ The package bundles the Hive3 agent skill, which teaches a coding agent how to use this CLI safely. Install it with one command:
39
66
 
40
67
  ```bash
41
- hive update
68
+ hive3 skill install
69
+ hive3 skill install --agent codex
70
+ hive3 skill install --agent cursor --project
71
+ hive3 skill path
72
+ hive3 skill show
42
73
  ```
43
74
 
44
- Use `hive update --check` to check without installing. Set `HIVE_NO_UPDATE_CHECK=1` to disable the automatic daily check. The check only requests public package metadata from npm and never sends Hive credentials.
75
+ | Agent | `install` (your account) | `install --project` (current directory) |
76
+ |---|---|---|
77
+ | Claude Code (default) | `~/.claude/skills/hive3` | `./.claude/skills/hive3` |
78
+ | Codex | `~/.agents/skills/hive3` | `./.agents/skills/hive3` |
79
+ | Cursor | `~/.cursor/skills/hive3` | `./.cursor/skills/hive3` |
80
+
81
+ For any other agent that reads Agent Skills, pass its skills directory: `hive3 skill install --dir <skills-dir>` installs into `<skills-dir>/hive3`. `--agent` accepts only the three agents above. `hive3 skill path` prints where `install` would write (same options), and `hive3 skill show` prints the skill itself. `install` refuses to overwrite a different existing `hive3` skill unless you add `--force`, and never writes through symlinks. Restart your agent afterwards if it was running; invoke the skill as `/hive3` (Claude Code, Cursor) or `$hive3` (Codex).
45
82
 
46
83
  ## Scopes
47
84
 
48
85
  Most users should use the login approval page's Read Only or Full Access choice:
49
86
 
50
87
  - Read Only: read account, community capability, post, and resource data.
51
- - Full Access: read/write API capabilities, including community admin actions where the person already has the live role. Account deletion requests still require an explicit confirmation command.
88
+ - Full Access: read/write API capabilities, including community admin actions where you already hold the live role.
52
89
 
53
90
  Advanced users can request exact scopes with repeated `--scope` flags.
54
91
 
55
- - `account:read` and `account:write`: profile, account preferences, wallets visibility, NFT exposure, export/deletion requests, uploads, and builder config.
92
+ - `account:read` and `account:write`: profile, account preferences, wallet visibility, NFT exposure, linked communities, uploads, builder config, notifications, and data exports (`hive3 account export`).
56
93
  - `posts:read` and `posts:write`: posts and comments.
57
94
  - `resources:read` and `resources:write`: events, courses, content, quests, jobs, participant workflows, evidence, attendance, progress, and applications.
58
- - `communities:read`, `communities:moderate`, and `communities:write`: capability discovery and current-role community membership/member workflows.
95
+ - `communities:read`, `communities:moderate`, and `communities:write`: capability discovery, managed-account targeting (`--account`), and current-role community membership/member workflows.
96
+ - `broadcasts:read` and `broadcasts:write`: broadcast emails. `tickets:read` and `tickets:write`: ticket listing and editing. `ai:read` and `ai:write`: the AI assistant and its documents. `credentials:read` and `credentials:write`: credential listing and awards. Search uses `resources:read`. Keys created before these scopes existed need a new `hive3 login` to get them.
59
97
 
60
- Scopes are necessary but not sufficient. Resource manager routes also require the person behind the key to be the owner or have the current community role. If `hive capabilities` returns an empty community list, personal commands can still work, but community-scoped commands should not be attempted.
98
+ A Full Access key can export all account data and change or remove wallet settings, so treat the key like a password. CLI keys can never delete an account: the `account:destroy` scope is never granted to the CLI.
99
+
100
+ Scopes are necessary but not sufficient. Resource manager routes also require the account behind the key to be the owner or to hold the current community role. If `hive3 capabilities` lists only your own account, personal commands work but community-scoped commands should not be attempted.
61
101
 
62
102
  ## Resource CRUD
63
103
 
64
104
  All resource commands print JSON.
65
105
 
66
106
  ```bash
67
- hive posts list
68
- hive posts create --body "Hello Hive"
69
- hive events create --title "Launch" --description "Details" --visibility public
70
- hive courses create --file course.json --idempotency-key course-001
71
- hive content update <content-id> --file content.json
72
- hive quests create --file quest.json
73
- hive jobs archive <job-id>
107
+ hive3 posts list
108
+ hive3 posts get <post-id>
109
+ hive3 posts create --body "Hello Hive"
110
+ hive3 events create --title "Launch" --description "Details" --visibility public
111
+ hive3 courses create --file course.json --idempotency-key course-001
112
+ hive3 content update <content-id> --file content.json
113
+ hive3 quests create --file quest.json
114
+ hive3 jobs archive <job-id>
74
115
  ```
75
116
 
76
- Supported resource families are `posts`, `events`, `courses`, `content`, `quests`, and `jobs`. Supported CRUD actions are `list`, `create`, `update <id>`, and `archive <id>`.
117
+ Supported resource families are `posts`, `events`, `courses`, `content`, `quests`, and `jobs`. Supported CRUD actions are `list`, `get <id>`, `create`, `update <id>`, and `archive <id>`. `--owner-type` and `--community-id` on `list` select which account's items to list; `--owner-type` alone is not a type filter.
77
118
 
78
- Community-targeted creates use the same person credential and the person's live community role:
119
+ Creating for a managed account uses the same key and your live role:
79
120
 
80
121
  ```bash
81
- hive posts create --body "Moderator update" --owner-type community --community-id <community-id>
122
+ hive3 posts create --body "Moderator update" --owner-type community --community-id <account-id>
82
123
  ```
83
124
 
84
- Complex payloads should use `--file <json>`. The JSON file must contain an object and is merged with command-line flags.
125
+ Events created through the CLI require RSVP approval by default; put `"autoEnroll": true` in the `--file` payload to auto-accept attendees. Resource lists are newest first, and `--cursor` pages through every item. Complex payloads should use `--file <json>`. The JSON file must contain an object and is merged with command-line flags.
85
126
 
86
127
  ## Uploads
87
128
 
88
129
  Upload images or documents first, then attach the returned storage ID through a profile/resource/workflow JSON payload.
89
130
 
90
131
  ```bash
91
- hive upload ./banner.png --purpose image
92
- hive upload ./resume.pdf --purpose document
132
+ hive3 upload ./banner.png --purpose image
133
+ hive3 upload ./resume.pdf --purpose document
93
134
  ```
94
135
 
95
- Allowed image types: GIF, JPEG, PNG, WebP up to 8 MB. Allowed document types: PDF, DOC, DOCX, Markdown, plain text up to 25 MB.
136
+ Allowed image types: GIF, JPEG, PNG, WebP up to 8 MB. Allowed document types: PDF, DOC, DOCX, Markdown, plain text up to 25 MB. Uploads are always made as the signed-in account; `--account` is not supported. Before sending any file the CLI checks the upload URL the server returns and refuses it unless it is `https` (plain `http` only for loopback development servers), points at the API host or a Convex host, and is the Hive storage upload path; no Hive credentials are sent to it.
96
137
 
97
138
  ## Workflow Commands
98
139
 
99
- Workflow commands use `/api/v1/workflows/*` and print stable JSON for agents.
140
+ Workflow commands use `/api/v1/workflows/*` and print stable JSON for agents. List commands are for managers of the resource.
100
141
 
101
142
  ```bash
102
- hive events participants <event-id>
103
- hive events rsvp <event-id> --enroll true
104
- hive events approve <event-id> <enrollment-id>
105
- hive events deny <event-id> <enrollment-id>
106
- hive events attendance <event-id> <enrollment-id>
107
-
108
- hive courses enroll <course-id>
109
- hive courses enrollments <course-id>
110
- hive courses approve <course-id> <person-id>
111
- hive courses deny <course-id> <person-id>
112
- hive courses complete <course-id> <lesson-id>
113
-
114
- hive quests enroll <quest-id>
115
- hive quests enrollments <quest-id>
116
- hive quests approve <quest-id> <enrollment-id>
117
- hive quests deny <quest-id> <enrollment-id>
118
- hive quests evidence submit <quest-id> --objective-id <objective-id> --content "https://proof.example" --file evidence.json
119
- hive quests evidence list <quest-id> --status pending
120
- hive quests evidence approve <quest-id> <evidence-id>
121
-
122
- hive jobs apply <job-id> --file application.json
123
- hive jobs applications <job-id>
124
- hive jobs applications
125
- hive jobs status <application-id> --status accepted
143
+ hive3 events participants <event-id>
144
+ hive3 events rsvp <event-id> --enroll true
145
+ hive3 events approve <event-id> <enrollment-id>
146
+ hive3 events deny <event-id> <enrollment-id>
147
+ hive3 events attendance <event-id> <enrollment-id>
148
+
149
+ hive3 courses enroll <course-id>
150
+ hive3 courses enrollments <course-id>
151
+ hive3 courses approve <course-id> <account-id>
152
+ hive3 courses deny <course-id> <account-id>
153
+ hive3 courses complete <course-id> <lesson-id>
154
+
155
+ hive3 quests enroll <quest-id>
156
+ hive3 quests enrollments <quest-id>
157
+ hive3 quests approve <quest-id> <enrollment-id>
158
+ hive3 quests deny <quest-id> <enrollment-id>
159
+ hive3 quests evidence submit <quest-id> --objective-id <objective-id> --content "https://proof.example" --file evidence.json
160
+ hive3 quests evidence list <quest-id> --status pending
161
+ hive3 quests evidence approve <quest-id> <evidence-id>
162
+ hive3 quests evidence deny <quest-id> <evidence-id>
163
+
164
+ hive3 jobs apply <job-id> --file application.json
165
+ hive3 jobs applications <job-id>
166
+ hive3 jobs applications
167
+ hive3 jobs status <application-id> --status accepted
126
168
  ```
127
169
 
170
+ Recording attendance needs an approved RSVP and works only on events that aren't archived. The first attendance time is kept, and clearing recorded attendance is refused. Approving a participant re-checks that they still have access to the event or course. RSVPs share the app's limits of 10 per minute and 100 per day. Deleting someone else's comment (on a post you don't own) needs the `communities:moderate` or `communities:write` scope. Keys never bypass role checks: to act on another account you need a real owner, admin or moderator role there.
171
+
172
+ Participant, enrollment and application lists include each person's primary email address when you manage the resource; handle that output accordingly.
173
+
128
174
  Job application JSON example:
129
175
 
130
176
  ```json
@@ -159,26 +205,115 @@ Quest evidence JSON example:
159
205
  }
160
206
  ```
161
207
 
162
- ## Personal Account Commands
208
+ ## Account Commands
209
+
210
+ ```bash
211
+ hive3 profile get
212
+ hive3 profile update --name "Ada" --image-storage-id <storage-id>
213
+ hive3 profile access --type open
214
+ hive3 profile overview save --file overview.json
215
+ hive3 profile update --account <account-id-or-handle> --name "Design Guild"
216
+ hive3 profile overview export --account <account-id-or-handle> --file overview.json
217
+ hive3 account get
218
+ hive3 account preferences --theme dark
219
+ hive3 account export
220
+ hive3 account linked-communities
221
+ hive3 account linked-communities disconnect <community-id> --confirm <community-id>
222
+ hive3 account deletion cancel
223
+ hive3 wallets list
224
+ hive3 wallets default <wallet-address>
225
+ hive3 wallets visibility <wallet-address> --public true
226
+ hive3 wallets remove <wallet-address> --confirm <wallet-address>
227
+ hive3 nfts visibility --public false
228
+ hive3 notifications list --unread-only
229
+ hive3 notifications unread-count
230
+ hive3 notifications mutes set --scope <scope> --muted true
231
+ hive3 comments create --post-id <post-id> --content "Nice work"
232
+ hive3 communities applications <community-id>
233
+ hive3 communities approve <application-id>
234
+ ```
235
+
236
+ ### Managing another account with `--account`
237
+
238
+ `--account <id-or-handle>` lets you act on an account where you are owner, admin or moderator. Give it once, after the action. It is supported by:
239
+
240
+ - `profile get`, `update`, `handle`, `access`, and every builder action (`overview`, `widgets`, `welcome-page` with `get`, `save`, `import`, `export`)
241
+ - `broadcasts list`, `audience`, `create`
242
+ - `tickets list`
243
+ - `assistant get`, `update`, `documents`, `documents add`
244
+ - `credentials list`
245
+
246
+ The key needs `communities:read` for reads or `communities:write` for writes, plus the live role. Moderators can't change roles or anything involving payments, and ticket management is for owners and admins only. Every other command acts as the signed-in account; use `--owner-type`/`--community-id` (resources) or the community commands to work on managed accounts.
247
+
248
+ ### Deleting an account
249
+
250
+ Account deletion cannot be requested from the CLI. Delete your account in the Hive app under Settings. If a deletion is pending, `hive3 account deletion cancel` cancels it.
251
+
252
+ ## Search, Broadcasts, Tickets, Assistant, Credentials
253
+
254
+ ```bash
255
+ hive3 search "design guild" --type accounts --limit 10
256
+ ```
257
+
258
+ `hive3 search <query> [--type all|accounts|events|courses|content|quests|jobs] [--limit 1-50] [--cursor c]` searches accounts and public resources you can see (query 1-100 characters, `resources:read`).
259
+
260
+ ### Broadcasts
261
+
262
+ Broadcasts are emails to an account's opted-in members. You need to be owner, admin or moderator.
263
+
264
+ ```bash
265
+ hive3 broadcasts audience --account <account-id-or-handle>
266
+ hive3 broadcasts create --subject "News" --body-text "Hello members" --account <account-id-or-handle>
267
+ hive3 broadcasts update <broadcast-id> --body-html "<p>Hello</p>" --body-mode html
268
+ hive3 broadcasts test <broadcast-id>
269
+ hive3 broadcasts send <broadcast-id> --yes
270
+ hive3 broadcasts send <broadcast-id> --yes --at 2026-12-01T15:00:00Z
271
+ hive3 broadcasts cancel <broadcast-id>
272
+ hive3 broadcasts list
273
+ hive3 broadcasts get <broadcast-id>
274
+ ```
275
+
276
+ `create` and `update` take `--subject`, `--body-text`, `--body-html`, `--body-mode editor|html`, `--hero-image-url` and `--file <json>` (flags override the file); drafts only. `update --remove-hero-image` removes the hero image. `test` emails the draft to your own address only. `send` emails every opted-in member (up to 5,000) and can't be undone once it starts, so it requires `--yes`; add `--at` to schedule it, and `cancel` returns a scheduled broadcast to draft. How often you can send depends on your plan: Honey Bee every 30 days, Swarm every 14, Royal every 7; Worker Bee can't send. There is no delete.
277
+
278
+ ### Tickets
279
+
280
+ ```bash
281
+ hive3 tickets list --account <account-id-or-handle>
282
+ hive3 tickets get <ticket-id>
283
+ hive3 tickets update <ticket-id> --amount 12.50 --currency USD --status inactive
284
+ hive3 tickets mine
285
+ ```
286
+
287
+ `tickets list` and `update` are for owners and admins of the selling account. `update` accepts `--name`, `--description`, `--amount` (decimal, at most two decimals), `--currency` and `--status active|inactive`; reactivating needs a Honey Bee or higher seller. Creating tickets, checkout and refunds are not available from the CLI.
288
+
289
+ ### AI assistant
290
+
291
+ ```bash
292
+ hive3 assistant get --account <account-id-or-handle>
293
+ hive3 assistant update --name "Helper" --description "Answers questions" --visibility private
294
+ hive3 assistant documents
295
+ hive3 assistant documents add ./faq.pdf
296
+ hive3 assistant documents delete <document-id> --confirm <document-id>
297
+ ```
298
+
299
+ The assistant needs a Honey Bee or higher account; the first `update` creates it. Documents are PDF, DOCX or plain text up to 5 MB (up to 50 per assistant). `documents add` uploads the file and registers it in one step. Chatting with the assistant is not available from the CLI.
300
+
301
+ ### Credentials
163
302
 
164
303
  ```bash
165
- hive profile get
166
- hive profile update --name "Ada" --image-storage-id <storage-id>
167
- hive profile access --type open
168
- hive profile overview save --file overview.json
169
- hive account preferences --theme dark
170
- hive account export
171
- hive wallets default <wallet-address>
172
- hive wallets visibility <wallet-address> --public true
173
- hive nfts visibility --public false
174
- hive notifications list
175
- hive comments create --post-id <post-id> --content "Nice work"
176
- hive communities applications <community-id>
177
- hive communities approve <application-id>
178
- ```
179
-
180
- Destructive or high-risk commands require explicit arguments such as exact IDs or confirmations. `archive`, member removal, role changes, application review, attendance recording, account deletion requests, and evidence/applicant decisions should be treated as confirmation-worthy in agent workflows.
304
+ hive3 credentials list --account <account-id-or-handle>
305
+ hive3 credentials get <credential-id>
306
+ hive3 credentials award <credential-id> --handles @alice,bob --yes
307
+ hive3 credentials mine
308
+ hive3 credentials claimable
309
+ ```
310
+
311
+ `award` gives a custom (general) credential to 1-50 accounts by handle and can't be undone through the CLI, so it requires `--yes`; people who already hold it are skipped. Creating, minting, deploying and claiming credentials are not available from the CLI.
312
+
313
+ ## Safety
314
+
315
+ Destructive or high-risk commands require explicit arguments such as exact IDs or confirmations: `wallets remove`, `communities remove-member`, `account linked-communities disconnect` and `assistant documents delete` need `--confirm <exact id>`; `broadcasts send` and `credentials award` need `--yes`. `archive`, role changes, application review, attendance recording, and evidence/applicant decisions should be treated as confirmation-worthy in agent workflows.
181
316
 
182
317
  ## Excluded Operations
183
318
 
184
- The CLI intentionally excludes wallet custody/signing/transfers, payment capture, credential minting/deployment/signature flows, private DMs, team/admin tools, migrations/imports/smoke helpers, community-owned API keys, community hard deletion, and arbitrary secret-bearing integration writes.
319
+ The CLI intentionally excludes wallet custody/signing/transfers, payment capture, credential creation, minting and claiming, ticket creation and refunds, AI assistant chat, private DMs, internal administration tools, migrations/imports/smoke helpers, community-owned API keys, account and community hard deletion, and arbitrary secret-bearing integration writes.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@hive3/cli",
3
- "version": "0.2.1",
4
- "description": "Command-line client for Hive's public API.",
3
+ "version": "0.4.0",
4
+ "description": "Command-line client for Hive3's public API.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "hive": "bin/hive.js",
@@ -10,6 +10,7 @@
10
10
  "files": [
11
11
  "bin",
12
12
  "src",
13
+ "skills",
13
14
  "README.md",
14
15
  "package.json"
15
16
  ],
@@ -17,8 +18,14 @@
17
18
  "access": "public"
18
19
  },
19
20
  "scripts": {
20
- "check": "node --check bin/hive.js && node --check src/api-client.js && node --check src/commands.js && node --check src/config.js && node --check src/extended-commands.js && node --check src/login.js && node --check src/update.js && node --check src/usage.js",
21
- "test": "node --test test/*.test.mjs"
21
+ "check": "node --check bin/hive.js && node --check src/api-client.js && node --check src/area-commands.js && node --check src/commands.js && node --check src/config.js && node --check src/extended-commands.js && node --check src/login.js && node --check src/shared.js && node --check src/update.js && node --check src/usage.js && node --check src/skill.js && node --check scripts/validate-skill.mjs",
22
+ "test": "node --test test/*.test.mjs",
23
+ "typecheck": "tsc -p tsconfig.json",
24
+ "validate:skill": "node scripts/validate-skill.mjs"
25
+ },
26
+ "devDependencies": {
27
+ "@types/node": "25.0.6",
28
+ "typescript": "5.9.3"
22
29
  },
23
30
  "engines": {
24
31
  "node": ">=20"
@@ -0,0 +1,170 @@
1
+ ---
2
+ name: hive3
3
+ description: Manage a user's Hive3 account through the Hive CLI and public API. Use when an agent needs to authenticate with `hive3 login`, inspect `hive3 whoami` or `hive3 capabilities`, or search and manage Hive3 profile, posts, events, courses, content, quests, jobs, comments, notifications, communities, broadcasts, tickets, the AI assistant, credentials, and participant workflows using only the user's approved credential and live permissions.
4
+ ---
5
+
6
+ # Hive3
7
+
8
+ Use the Hive3 CLI (`hive3`) as the safe interface for programmatic Hive3 account work. Credentials belong to the signed-in account only. Hive3 accounts are unified: a profile and a community are the same kind of account, and the key can act on another account only while the signed-in user currently has the needed owner, admin, or moderator role there.
9
+
10
+ ## Start Safely
11
+
12
+ 1. Confirm the CLI is available with `hive3 --help`. If it is missing, ask the user to install it with `npm install --global @hive3/cli` (Node.js 20 or newer).
13
+ 2. Run `hive3 whoami` before account or resource work.
14
+ 3. If the CLI is not authenticated, ask the user to run `hive3 login` or run it only when the user has asked you to connect the CLI. The user must approve in the browser and should approve only the code shown in their own terminal. Creating a key needs a Honey Bee plan or above.
15
+ 4. Run `hive3 capabilities` before acting on any account other than the user's own.
16
+ 5. If only the user's own account is listed, report that no managed-account commands are available for this key.
17
+ 6. Run `hive3 <command> --help` for exact actions and flags; help needs no login.
18
+ 7. To refresh this skill after a CLI update, run `hive3 update` and then `hive3 skill install --force`.
19
+
20
+ ## Permission Rules
21
+
22
+ - Do not create, request, or use community-owned API keys.
23
+ - Do not ask the user to paste API key secrets into chat. Use `hive3 login` for browser approval.
24
+ - Treat the credential as belonging to the signed-in user. Access to other accounts is derived from live roles and can disappear.
25
+ - Use `--owner-type community --community-id <id>` (resources) or `--account <id-or-handle>` (the commands below that support it) only after `hive3 capabilities` shows the target account and sufficient capability.
26
+ - Ask for explicit confirmation before destructive or hard-to-undo actions such as `archive`, member removal, role changes, application decisions, attendance recording, evidence review, wallet removal, disconnecting a linked community, sending a broadcast, awarding a credential, deleting an assistant document, or replacing builder JSON, unless the user has already given precise approval for that exact action.
27
+ - Never add `--yes` or `--confirm` on your own initiative. Add it only after the user has approved the exact action; show the target ID and effect first.
28
+ - If an API error reports `insufficient_scope`, explain the missing scopes and suggest re-running `hive3 login --scope ...`; do not suggest a community key.
29
+ - If the API reports `forbidden`, explain that the key has the scope but the signed-in user no longer has the live role/capability for that target.
30
+ - If the CLI reports that the plan doesn't include API access (`plan_required`), tell the user the API needs Honey Bee or above and that they can upgrade under Settings in the Hive app; the key works again afterwards without logging in again. Do not retry in a loop.
31
+ - Account deletion cannot be requested from the CLI. If the user wants to delete their account, tell them to do it in the Hive app under Settings. `hive3 account deletion cancel` only cancels a pending deletion.
32
+
33
+ ## Identity And Capability Checks
34
+
35
+ Use:
36
+
37
+ ```bash
38
+ hive3 whoami
39
+ hive3 capabilities
40
+ ```
41
+
42
+ Interpret the output literally:
43
+
44
+ - `whoami` identifies the signed-in account, the credential scopes, and how many accounts the key can act on.
45
+ - `capabilities` lists those accounts with the user's role and role-derived actions. The user's own account appears there too; presence alone does not prove management permission, so read the listed actions.
46
+ - If only the user's own account is listed, personal commands still work, but managed-account commands should not be attempted.
47
+
48
+ ## Resource Commands
49
+
50
+ Personal examples:
51
+
52
+ ```bash
53
+ hive3 posts list
54
+ hive3 posts get <post-id>
55
+ hive3 posts create --body "Update from Hive3"
56
+ hive3 events create --title "Launch" --description "Details" --visibility public
57
+ hive3 courses create --file course.json
58
+ hive3 content update <content-id> --file content.json
59
+ hive3 quests create --file quest.json
60
+ hive3 jobs create --file job.json
61
+ ```
62
+
63
+ Managed-account create example, only after capability verification:
64
+
65
+ ```bash
66
+ hive3 posts create --body "Moderator update" --owner-type community --community-id <account-id>
67
+ ```
68
+
69
+ Supported resource families are `posts`, `events`, `courses`, `content`, `quests`, and `jobs`. Supported actions are `list`, `get <id>`, `create`, `update <id>`, and `archive <id>`. Use `--file <json>` for complex events, courses, content, quests, and jobs. `--owner-type`/`--community-id` on `list` choose whose items to list; `--owner-type` alone is not a type filter.
70
+
71
+ ## Account, Social, And Community Commands
72
+
73
+ Use these only when the requested work calls for them:
74
+
75
+ ```bash
76
+ hive3 search "design guild" --type accounts
77
+ hive3 profile get
78
+ hive3 profile update --name "Ada" --image-storage-id <storage-id>
79
+ hive3 profile overview save --file overview.json
80
+ hive3 profile update --account <account-id-or-handle> --name "Design Guild"
81
+ hive3 upload ./banner.png --purpose image
82
+ hive3 account get
83
+ hive3 account preferences --theme dark
84
+ hive3 account linked-communities
85
+ hive3 wallets visibility <wallet-address> --public true
86
+ hive3 nfts visibility --public false
87
+ hive3 notifications list --unread-only
88
+ hive3 notifications unread-count
89
+ hive3 comments create --post-id <post-id> --content "Nice work"
90
+ hive3 communities applications <community-id>
91
+ hive3 communities members <community-id>
92
+ hive3 communities role <community-id> <account-id> --role moderator
93
+ ```
94
+
95
+ `--account <id-or-handle>` (given once, after the action) is supported by `hive3 profile` actions (including the builders), `hive3 broadcasts list|audience|create`, `hive3 tickets list`, `hive3 assistant ...`, and `hive3 credentials list`. Reads need `communities:read`, writes `communities:write`. Everything else acts as the signed-in account; `hive3 upload` always uploads as the signed-in user, so attach the returned storage ID with `--account`. Moderators can't change roles or anything involving payments; owners and admins can.
96
+
97
+ ## Broadcasts, Tickets, Assistant, And Credentials
98
+
99
+ ```bash
100
+ hive3 broadcasts audience
101
+ hive3 broadcasts create --subject "News" --body-text "Hello" --account <account-id-or-handle>
102
+ hive3 broadcasts test <broadcast-id>
103
+ hive3 broadcasts send <broadcast-id> --yes
104
+ hive3 broadcasts send <broadcast-id> --yes --at 2026-12-01T15:00:00Z
105
+ hive3 broadcasts cancel <broadcast-id>
106
+
107
+ hive3 tickets list
108
+ hive3 tickets update <ticket-id> --status inactive
109
+ hive3 tickets mine
110
+
111
+ hive3 assistant get
112
+ hive3 assistant update --name "Helper" --visibility private
113
+ hive3 assistant documents add ./faq.pdf
114
+ hive3 assistant documents delete <document-id> --confirm <document-id>
115
+
116
+ hive3 credentials list
117
+ hive3 credentials mine
118
+ hive3 credentials claimable
119
+ hive3 credentials award <credential-id> --handles @alice,bob --yes
120
+ ```
121
+
122
+ - Broadcasts email opted-in members (up to 5,000) and an immediate send cannot be undone. Create a draft, run `hive3 broadcasts test <id>` (emails only the signed-in user), show the user the subject, audience from `hive3 broadcasts audience`, and schedule, and send only after they approve. Sending is limited by plan (Honey Bee every 30 days, Swarm 14, Royal 7; Worker Bee can't send). A scheduled broadcast can be returned to draft with `cancel`. There is no delete.
123
+ - Tickets can be viewed and edited (name, description, price, currency, active/inactive). Creating tickets, checkout, capture, and refunds are not available. Ticket management is for owners and admins, not moderators.
124
+ - The assistant needs a Honey Bee or higher account; documents are PDF, DOCX, or plain text up to 5 MB. Chatting with the assistant is not available.
125
+ - Credentials can be read and custom credentials awarded; awards can't be undone through the CLI. Creating, minting, deploying, and claiming are not available.
126
+ - New scopes for these areas are `broadcasts:*`, `tickets:*`, `ai:*`, and `credentials:*` (`read`/`write`). Key bundles from `hive3 login --access` include them; keys created earlier may need a new login.
127
+
128
+ ## Workflow Commands
129
+
130
+ Use workflow commands for operational management after resources exist:
131
+
132
+ ```bash
133
+ hive3 events participants <event-id>
134
+ hive3 events rsvp <event-id> --enroll true
135
+ hive3 events approve <event-id> <enrollment-id>
136
+ hive3 events attendance <event-id> <enrollment-id>
137
+
138
+ hive3 courses enrollments <course-id>
139
+ hive3 courses approve <course-id> <account-id>
140
+ hive3 courses complete <course-id> <lesson-id>
141
+
142
+ hive3 quests enrollments <quest-id>
143
+ hive3 quests evidence submit <quest-id> --objective-id <objective-id> --content "https://proof.example" --file evidence.json
144
+ hive3 quests evidence approve <quest-id> <evidence-id>
145
+
146
+ hive3 jobs apply <job-id> --file application.json
147
+ hive3 jobs applications <job-id>
148
+ hive3 jobs status <application-id> --status accepted
149
+ ```
150
+
151
+ Workflow outputs are JSON. Participant, enrollment, and application lists include people's primary email addresses for managers, so do not repeat them beyond what the task needs. Attendance can be recorded only for approved RSVPs on non-archived events (an unapproved RSVP returns 409 "Approved RSVP required"), and recorded attendance can't be cleared. Events created through the CLI need RSVP approval unless the payload sets `autoEnroll: true`. Deleting another person's comment needs `communities:moderate` or `communities:write`. If a 429 appears (RSVPs are limited to 10 per minute and 100 per day), stop and report instead of retrying. Before approving, denying, recording attendance, or changing application status, identify the target resource and the account/application/evidence ID in your summary and confirm the user intended that action.
152
+
153
+ ## Uploads And JSON Files
154
+
155
+ Use `hive3 upload <file> --purpose image|document` before attaching media or documents. Then place the returned storage ID in a JSON payload. Allowed uploads are images up to 8 MB and documents up to 25 MB. Job applications require a `resume` object; quest evidence can include safe attachment descriptors.
156
+
157
+ ## Exclusions
158
+
159
+ Never use the Hive CLI or public API for wallet custody, private-key handling, signing, transfers, gas sponsorship changes, payment capture, credential mint/deploy/claim/signature flows, private DMs, internal administration tools, migrations/imports/smoke helpers, community-owned API keys, account or community hard deletion, or arbitrary secret-bearing integration writes.
160
+
161
+ ## Reporting
162
+
163
+ After running commands, summarize:
164
+
165
+ - Which account was used when identity matters.
166
+ - Which managed account was targeted, if any.
167
+ - What changed, including returned resource IDs.
168
+ - Any missing permission or scope in plain language.
169
+
170
+ Never print stored API keys, config file contents, bearer tokens, or upload URLs that should stay private.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Hive3"
3
+ short_description: "Manage Hive3 through the CLI safely"
4
+ default_prompt: "Use $hive3 to check my Hive3 account capabilities and manage approved resources."