@hive3/cli 0.3.0 → 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 +216 -87
- package/package.json +6 -4
- package/skills/hive3/SKILL.md +170 -0
- package/skills/hive3/agents/openai.yaml +4 -0
- package/src/api-client.js +87 -8
- package/src/area-commands.js +385 -0
- package/src/commands.js +67 -44
- package/src/config.js +31 -9
- package/src/extended-commands.js +15 -44
- package/src/login.js +11 -6
- package/src/shared.js +86 -0
- package/src/skill.js +212 -0
- package/src/update.js +30 -17
- package/src/usage.js +277 -12
package/README.md
CHANGED
|
@@ -1,132 +1,176 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Hive3 CLI
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
25
|
-
|
|
23
|
+
hive3 login --access read
|
|
24
|
+
hive3 login --access full
|
|
26
25
|
```
|
|
27
26
|
|
|
28
|
-
Approving a login requires a Honey Bee (or higher)
|
|
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
|
-
The CLI stores
|
|
33
|
+
The CLI stores the API key, API URL, key prefix and scopes in a `config.json` file:
|
|
31
34
|
|
|
32
|
-
|
|
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` |
|
|
33
41
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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.
|
|
37
52
|
|
|
38
53
|
## Updating
|
|
39
54
|
|
|
40
|
-
The CLI checks npm for a
|
|
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:
|
|
41
66
|
|
|
42
67
|
```bash
|
|
43
|
-
|
|
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
|
|
44
73
|
```
|
|
45
74
|
|
|
46
|
-
|
|
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).
|
|
47
82
|
|
|
48
83
|
## Scopes
|
|
49
84
|
|
|
50
85
|
Most users should use the login approval page's Read Only or Full Access choice:
|
|
51
86
|
|
|
52
87
|
- Read Only: read account, community capability, post, and resource data.
|
|
53
|
-
- Full Access: read/write API capabilities, including community admin actions where
|
|
88
|
+
- Full Access: read/write API capabilities, including community admin actions where you already hold the live role.
|
|
54
89
|
|
|
55
90
|
Advanced users can request exact scopes with repeated `--scope` flags.
|
|
56
91
|
|
|
57
|
-
- `account:read` and `account:write`: profile, account preferences,
|
|
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`).
|
|
58
93
|
- `posts:read` and `posts:write`: posts and comments.
|
|
59
94
|
- `resources:read` and `resources:write`: events, courses, content, quests, jobs, participant workflows, evidence, attendance, progress, and applications.
|
|
60
|
-
- `communities:read`, `communities:moderate`, and `communities:write`: capability discovery, managed-account
|
|
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.
|
|
97
|
+
|
|
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.
|
|
61
99
|
|
|
62
|
-
Scopes are necessary but not sufficient. Resource manager routes also require the
|
|
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.
|
|
63
101
|
|
|
64
102
|
## Resource CRUD
|
|
65
103
|
|
|
66
104
|
All resource commands print JSON.
|
|
67
105
|
|
|
68
106
|
```bash
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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>
|
|
76
115
|
```
|
|
77
116
|
|
|
78
|
-
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.
|
|
79
118
|
|
|
80
|
-
|
|
119
|
+
Creating for a managed account uses the same key and your live role:
|
|
81
120
|
|
|
82
121
|
```bash
|
|
83
|
-
|
|
122
|
+
hive3 posts create --body "Moderator update" --owner-type community --community-id <account-id>
|
|
84
123
|
```
|
|
85
124
|
|
|
86
|
-
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.
|
|
87
126
|
|
|
88
127
|
## Uploads
|
|
89
128
|
|
|
90
129
|
Upload images or documents first, then attach the returned storage ID through a profile/resource/workflow JSON payload.
|
|
91
130
|
|
|
92
131
|
```bash
|
|
93
|
-
|
|
94
|
-
|
|
132
|
+
hive3 upload ./banner.png --purpose image
|
|
133
|
+
hive3 upload ./resume.pdf --purpose document
|
|
95
134
|
```
|
|
96
135
|
|
|
97
|
-
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.
|
|
98
137
|
|
|
99
138
|
## Workflow Commands
|
|
100
139
|
|
|
101
|
-
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.
|
|
102
141
|
|
|
103
142
|
```bash
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
|
128
168
|
```
|
|
129
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
|
+
|
|
130
174
|
Job application JSON example:
|
|
131
175
|
|
|
132
176
|
```json
|
|
@@ -161,30 +205,115 @@ Quest evidence JSON example:
|
|
|
161
205
|
}
|
|
162
206
|
```
|
|
163
207
|
|
|
164
|
-
##
|
|
208
|
+
## Account Commands
|
|
165
209
|
|
|
166
210
|
```bash
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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
|
|
302
|
+
|
|
303
|
+
```bash
|
|
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.
|
|
187
316
|
|
|
188
317
|
## Excluded Operations
|
|
189
318
|
|
|
190
|
-
The CLI intentionally excludes wallet custody/signing/transfers, payment capture, credential minting
|
|
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.
|
|
4
|
-
"description": "Command-line client for
|
|
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,9 +18,10 @@
|
|
|
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
|
+
"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",
|
|
21
22
|
"test": "node --test test/*.test.mjs",
|
|
22
|
-
"typecheck": "tsc -p tsconfig.json"
|
|
23
|
+
"typecheck": "tsc -p tsconfig.json",
|
|
24
|
+
"validate:skill": "node scripts/validate-skill.mjs"
|
|
23
25
|
},
|
|
24
26
|
"devDependencies": {
|
|
25
27
|
"@types/node": "25.0.6",
|
|
@@ -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.
|