@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 +217 -82
- package/package.json +11 -4
- package/skills/hive3/SKILL.md +170 -0
- package/skills/hive3/agents/openai.yaml +4 -0
- package/src/api-client.js +99 -20
- package/src/area-commands.js +385 -0
- package/src/commands.js +89 -50
- 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 +278 -13
package/src/skill.js
ADDED
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
|
|
3
|
+
import { chmod, lstat, mkdir, mkdtemp, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
|
|
4
|
+
import os from "node:os";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
|
|
8
|
+
import { requiredFlagValue, writeLine } from "./shared.js";
|
|
9
|
+
import { commandUsage } from "./usage.js";
|
|
10
|
+
|
|
11
|
+
export const SKILL_NAME = "hive3";
|
|
12
|
+
const SKILL_SOURCE = new URL("../skills/hive3/", import.meta.url);
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Skills directories verified against each agent's documentation (October 2026):
|
|
16
|
+
* - Claude Code: ~/.claude/skills/<name>/SKILL.md and .claude/skills/<name>/SKILL.md
|
|
17
|
+
* - Codex: $HOME/.agents/skills and $REPO/.agents/skills (~/.codex/skills is deprecated)
|
|
18
|
+
* - Cursor: ~/.cursor/skills and .cursor/skills
|
|
19
|
+
* @type {Record<string, { label: string, user: string[], project: string[], invoke: string }>}
|
|
20
|
+
*/
|
|
21
|
+
const AGENTS = {
|
|
22
|
+
claude: { invoke: "/hive3", label: "Claude Code", project: [".claude", "skills"], user: [".claude", "skills"] },
|
|
23
|
+
codex: { invoke: "$hive3", label: "Codex", project: [".agents", "skills"], user: [".agents", "skills"] },
|
|
24
|
+
cursor: { invoke: "/hive3", label: "Cursor", project: [".cursor", "skills"], user: [".cursor", "skills"] },
|
|
25
|
+
};
|
|
26
|
+
const DEFAULT_AGENT = "claude";
|
|
27
|
+
|
|
28
|
+
export function skillUsage() {
|
|
29
|
+
return /** @type {string} */ (commandUsage("skill"));
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @param {string[]} args
|
|
34
|
+
*/
|
|
35
|
+
function parseTargetArgs(args) {
|
|
36
|
+
const options = { agent: undefined, dir: undefined, force: false, project: false };
|
|
37
|
+
for (let index = 0; index < args.length; index += 1) {
|
|
38
|
+
const flag = args[index];
|
|
39
|
+
if (flag === "--agent") {
|
|
40
|
+
index += 1;
|
|
41
|
+
options.agent = requiredFlagValue(flag, args[index]);
|
|
42
|
+
} else if (flag === "--dir") {
|
|
43
|
+
index += 1;
|
|
44
|
+
options.dir = requiredFlagValue(flag, args[index]);
|
|
45
|
+
} else if (flag === "--project") {
|
|
46
|
+
options.project = true;
|
|
47
|
+
} else if (flag === "--force") {
|
|
48
|
+
options.force = true;
|
|
49
|
+
} else {
|
|
50
|
+
throw new Error(`Unknown skill option: ${flag}`);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
if (options.dir !== undefined && (options.agent !== undefined || options.project)) {
|
|
54
|
+
throw new Error("--dir cannot be combined with --agent or --project.");
|
|
55
|
+
}
|
|
56
|
+
return options;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Resolve the folder the skill is installed into (`<skills dir>/hive3`).
|
|
61
|
+
* @param {{ agent?: string, dir?: string, project: boolean }} options
|
|
62
|
+
* @param {{ cwd?: string, homeDir?: string }} deps
|
|
63
|
+
*/
|
|
64
|
+
export function resolveSkillTarget(options, deps) {
|
|
65
|
+
const cwd = deps.cwd ?? process.cwd();
|
|
66
|
+
if (options.dir !== undefined) {
|
|
67
|
+
return { agent: undefined, target: path.join(path.resolve(cwd, options.dir), SKILL_NAME) };
|
|
68
|
+
}
|
|
69
|
+
const agent = options.agent ?? DEFAULT_AGENT;
|
|
70
|
+
const spec = Object.hasOwn(AGENTS, agent) ? AGENTS[agent] : undefined;
|
|
71
|
+
if (!spec) {
|
|
72
|
+
throw new Error(
|
|
73
|
+
`Unknown agent "${agent}". Supported: ${Object.keys(AGENTS).join(", ")}. For any other agent, use --dir <skills directory>.`,
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
const base = options.project ? cwd : (deps.homeDir ?? os.homedir());
|
|
77
|
+
return { agent, target: path.join(base, ...(options.project ? spec.project : spec.user), SKILL_NAME) };
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* @typedef {{ relative: string, executable: boolean, content: Buffer }} SkillFile
|
|
82
|
+
* @returns {Promise<SkillFile[]>}
|
|
83
|
+
*/
|
|
84
|
+
async function readBundledSkill() {
|
|
85
|
+
const root = fileURLToPath(SKILL_SOURCE);
|
|
86
|
+
/** @type {SkillFile[]} */
|
|
87
|
+
const files = [];
|
|
88
|
+
/** @param {string} relative */
|
|
89
|
+
async function walk(relative) {
|
|
90
|
+
const directory = path.join(root, relative);
|
|
91
|
+
for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
|
|
92
|
+
const entryRelative = path.join(relative, entry.name);
|
|
93
|
+
const full = path.join(root, entryRelative);
|
|
94
|
+
const info = await lstat(full);
|
|
95
|
+
if (info.isDirectory()) await walk(entryRelative);
|
|
96
|
+
else if (info.isFile()) {
|
|
97
|
+
files.push({ content: await readFile(full), executable: (info.mode & 0o111) !== 0, relative: entryRelative });
|
|
98
|
+
} else {
|
|
99
|
+
throw new Error(`The bundled skill contains an unsupported entry: ${entryRelative}`);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
await walk("");
|
|
104
|
+
if (!files.some((file) => file.relative === "SKILL.md")) throw new Error("The bundled Hive3 skill is missing SKILL.md.");
|
|
105
|
+
return files;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Whether `target` already holds exactly the bundled files (and nothing else).
|
|
110
|
+
* Throws if the target, or anything inside it, is a symlink.
|
|
111
|
+
* @param {string} target
|
|
112
|
+
* @param {SkillFile[]} files
|
|
113
|
+
*/
|
|
114
|
+
async function existingState(target, files) {
|
|
115
|
+
const info = await lstat(target).catch((error) => {
|
|
116
|
+
if (error?.code === "ENOENT") return undefined;
|
|
117
|
+
throw error;
|
|
118
|
+
});
|
|
119
|
+
if (!info) return "absent";
|
|
120
|
+
if (info.isSymbolicLink()) {
|
|
121
|
+
throw new Error(`${target} is a symlink; remove it first. The CLI never writes through symlinks.`);
|
|
122
|
+
}
|
|
123
|
+
if (!info.isDirectory()) throw new Error(`${target} exists and is not a directory; remove it first.`);
|
|
124
|
+
const expected = new Map(files.map((file) => [file.relative, file]));
|
|
125
|
+
/** @param {string} relative */
|
|
126
|
+
async function compare(relative) {
|
|
127
|
+
for (const entry of await readdir(path.join(target, relative), { withFileTypes: true })) {
|
|
128
|
+
const entryRelative = path.join(relative, entry.name);
|
|
129
|
+
const full = path.join(target, entryRelative);
|
|
130
|
+
const entryInfo = await lstat(full);
|
|
131
|
+
if (entryInfo.isSymbolicLink()) {
|
|
132
|
+
throw new Error(`${full} is a symlink; remove it first. The CLI never writes through symlinks.`);
|
|
133
|
+
}
|
|
134
|
+
if (entryInfo.isDirectory()) {
|
|
135
|
+
if (!(await compare(entryRelative))) return false;
|
|
136
|
+
} else {
|
|
137
|
+
const file = expected.get(entryRelative);
|
|
138
|
+
if (!file || !entryInfo.isFile() || !file.content.equals(await readFile(full))) return false;
|
|
139
|
+
expected.delete(entryRelative);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return true;
|
|
143
|
+
}
|
|
144
|
+
return (await compare("")) && expected.size === 0 ? "same" : "different";
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Stage a complete copy beside the target, then swap it in, so a failure never leaves a half-written skill.
|
|
149
|
+
* @param {string} target
|
|
150
|
+
* @param {SkillFile[]} files
|
|
151
|
+
* @param {boolean} replace
|
|
152
|
+
*/
|
|
153
|
+
async function writeSkill(target, files, replace) {
|
|
154
|
+
const skillsDir = path.dirname(target);
|
|
155
|
+
await mkdir(skillsDir, { recursive: true });
|
|
156
|
+
const staging = await mkdtemp(path.join(skillsDir, `.${SKILL_NAME}-`));
|
|
157
|
+
try {
|
|
158
|
+
for (const file of files) {
|
|
159
|
+
const destination = path.join(staging, file.relative);
|
|
160
|
+
await mkdir(path.dirname(destination), { recursive: true });
|
|
161
|
+
await writeFile(destination, file.content, { flag: "wx" });
|
|
162
|
+
await chmod(destination, file.executable ? 0o755 : 0o644);
|
|
163
|
+
}
|
|
164
|
+
for (const directory of new Set(files.map((file) => path.dirname(path.join(staging, file.relative))))) {
|
|
165
|
+
await chmod(directory, 0o755);
|
|
166
|
+
}
|
|
167
|
+
await chmod(staging, 0o755);
|
|
168
|
+
if (replace) await rm(target, { force: true, recursive: true });
|
|
169
|
+
await rename(staging, target);
|
|
170
|
+
} catch (error) {
|
|
171
|
+
await rm(staging, { force: true, recursive: true });
|
|
172
|
+
throw error;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* @param {string[]} args
|
|
178
|
+
* @param {{ cwd?: string, homeDir?: string, stdout: { write(chunk: string): unknown } }} deps
|
|
179
|
+
*/
|
|
180
|
+
export async function runSkill(args, deps) {
|
|
181
|
+
const [action, ...rest] = args;
|
|
182
|
+
if (!action || action === "--help" || action === "-h" || action === "help") {
|
|
183
|
+
writeLine(deps.stdout, skillUsage());
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
if (action === "show") {
|
|
187
|
+
if (rest.length > 0) throw new Error(`Unknown skill show option: ${rest[0]}`);
|
|
188
|
+
const skill = (await readBundledSkill()).find((file) => file.relative === "SKILL.md");
|
|
189
|
+
deps.stdout.write(skill?.content.toString("utf8") ?? "");
|
|
190
|
+
return;
|
|
191
|
+
}
|
|
192
|
+
if (action !== "install" && action !== "path") throw new Error(`Unknown skill action: ${action}`);
|
|
193
|
+
const options = parseTargetArgs(rest);
|
|
194
|
+
const { agent, target } = resolveSkillTarget(options, deps);
|
|
195
|
+
if (action === "path") {
|
|
196
|
+
writeLine(deps.stdout, target);
|
|
197
|
+
return;
|
|
198
|
+
}
|
|
199
|
+
const files = await readBundledSkill();
|
|
200
|
+
const state = await existingState(target, files);
|
|
201
|
+
if (state === "same") {
|
|
202
|
+
writeLine(deps.stdout, `The Hive3 skill is already installed and up to date at ${target}.`);
|
|
203
|
+
return;
|
|
204
|
+
}
|
|
205
|
+
if (state === "different" && !options.force) {
|
|
206
|
+
throw new Error(`A different skill already exists at ${target}. Re-run with --force to replace it.`);
|
|
207
|
+
}
|
|
208
|
+
await writeSkill(target, files, state === "different");
|
|
209
|
+
const spec = agent ? AGENTS[agent] : undefined;
|
|
210
|
+
writeLine(deps.stdout, `Installed the Hive3 skill at ${target}.`);
|
|
211
|
+
if (spec) writeLine(deps.stdout, `Restart ${spec.label} if it is running, then use ${spec.invoke} or just ask it to use Hive3.`);
|
|
212
|
+
}
|
package/src/update.js
CHANGED
|
@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
|
|
|
5
5
|
import { promises as fs } from "node:fs";
|
|
6
6
|
import path from "node:path";
|
|
7
7
|
|
|
8
|
-
import { configDirectory } from "./config.js";
|
|
8
|
+
import { configDirectory, writePrivateFile } from "./config.js";
|
|
9
9
|
|
|
10
10
|
export const PACKAGE_NAME = "@hive3/cli";
|
|
11
11
|
export const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@hive3%2Fcli/latest";
|
|
@@ -97,11 +97,7 @@ async function loadUpdateCache(file) {
|
|
|
97
97
|
}
|
|
98
98
|
|
|
99
99
|
async function saveUpdateCache(file, cache) {
|
|
100
|
-
|
|
101
|
-
await fs.mkdir(directory, { mode: 0o700, recursive: true });
|
|
102
|
-
const temporaryFile = `${file}.${process.pid}.tmp`;
|
|
103
|
-
await fs.writeFile(temporaryFile, `${JSON.stringify(cache)}\n`, { mode: 0o600 });
|
|
104
|
-
await fs.rename(temporaryFile, file);
|
|
100
|
+
await writePrivateFile(path.dirname(file), path.basename(file), `${JSON.stringify(cache)}\n`);
|
|
105
101
|
}
|
|
106
102
|
|
|
107
103
|
export async function maybeNotifyUpdate(overrides = {}) {
|
|
@@ -143,18 +139,27 @@ export async function maybeNotifyUpdate(overrides = {}) {
|
|
|
143
139
|
if (compareVersions(latestVersion, currentVersion) <= 0) return null;
|
|
144
140
|
|
|
145
141
|
writeLine(stderr, `Hive CLI update available: ${currentVersion} → ${latestVersion}`);
|
|
146
|
-
writeLine(stderr, "Run `
|
|
142
|
+
writeLine(stderr, "Run `hive3 update` to install it.");
|
|
147
143
|
return latestVersion;
|
|
148
144
|
}
|
|
149
145
|
|
|
150
|
-
|
|
146
|
+
/**
|
|
147
|
+
* Install the exact version the user was shown. The version is validated against a
|
|
148
|
+
* strict semver pattern, so the only variable argument can never carry shell syntax.
|
|
149
|
+
* Windows resolves `npm` through `npm.cmd`, which Node (CVE-2024-27980 fix) refuses to
|
|
150
|
+
* spawn without a shell; the arguments are fixed and validated there, so `shell: true`
|
|
151
|
+
* is safe on win32 only.
|
|
152
|
+
*/
|
|
153
|
+
export function installVersion(version, overrides = {}) {
|
|
154
|
+
parseVersion(version);
|
|
151
155
|
const spawnImpl = overrides.spawn ?? spawn;
|
|
152
|
-
const
|
|
156
|
+
const windows = (overrides.platform ?? process.platform) === "win32";
|
|
153
157
|
return new Promise((resolve, reject) => {
|
|
154
|
-
const child = spawnImpl(
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
+
const child = spawnImpl(
|
|
159
|
+
windows ? "npm.cmd" : "npm",
|
|
160
|
+
["install", "--global", `${PACKAGE_NAME}@${version}`],
|
|
161
|
+
{ shell: windows, stdio: "inherit" },
|
|
162
|
+
);
|
|
158
163
|
child.once("error", reject);
|
|
159
164
|
child.once("exit", (code, signal) => {
|
|
160
165
|
if (code === 0) resolve(undefined);
|
|
@@ -163,13 +168,21 @@ export function installLatest(overrides = {}) {
|
|
|
163
168
|
});
|
|
164
169
|
}
|
|
165
170
|
|
|
171
|
+
export function updateUsage() {
|
|
172
|
+
return [
|
|
173
|
+
"Usage: hive3 update [--check]",
|
|
174
|
+
" --check Report the latest published version without installing it.",
|
|
175
|
+
"Installs exactly the version it reports (npm install --global @hive3/cli@<version>).",
|
|
176
|
+
].join("\n");
|
|
177
|
+
}
|
|
178
|
+
|
|
166
179
|
export async function runUpdateCommand(args, overrides = {}) {
|
|
167
180
|
const stdout = overrides.stdout ?? process.stdout;
|
|
168
181
|
if (args.length > 1 || (args.length === 1 && !["--check", "--help", "-h"].includes(args[0]))) {
|
|
169
182
|
throw new Error(`Unknown update option: ${args[0] ?? ""}`.trim());
|
|
170
183
|
}
|
|
171
184
|
if (args[0] === "--help" || args[0] === "-h") {
|
|
172
|
-
writeLine(stdout,
|
|
185
|
+
writeLine(stdout, updateUsage());
|
|
173
186
|
return;
|
|
174
187
|
}
|
|
175
188
|
|
|
@@ -189,11 +202,11 @@ export async function runUpdateCommand(args, overrides = {}) {
|
|
|
189
202
|
|
|
190
203
|
if (args[0] === "--check") {
|
|
191
204
|
writeLine(stdout, `Hive CLI update available: ${currentVersion} → ${latestVersion}`);
|
|
192
|
-
writeLine(stdout, "Run `
|
|
205
|
+
writeLine(stdout, "Run `hive3 update` to install it.");
|
|
193
206
|
return;
|
|
194
207
|
}
|
|
195
208
|
|
|
196
209
|
writeLine(stdout, `Updating Hive CLI ${currentVersion} → ${latestVersion}...`);
|
|
197
|
-
await (overrides.install ??
|
|
198
|
-
writeLine(stdout, `Hive CLI ${latestVersion} installed. Run \`
|
|
210
|
+
await (overrides.install ?? installVersion)(latestVersion, { platform: overrides.platform, spawn: overrides.spawn });
|
|
211
|
+
writeLine(stdout, `Hive CLI ${latestVersion} installed. Run \`hive3 --help\` to verify it.`);
|
|
199
212
|
}
|
package/src/usage.js
CHANGED
|
@@ -2,40 +2,96 @@
|
|
|
2
2
|
|
|
3
3
|
export function usage() {
|
|
4
4
|
return [
|
|
5
|
-
"Usage:
|
|
5
|
+
"Usage: hive3 <command> [options]",
|
|
6
|
+
"",
|
|
7
|
+
"Run `hive3 <command> --help` for the actions and flags of one command.",
|
|
6
8
|
"",
|
|
7
9
|
"Commands:",
|
|
8
10
|
" login Connect this CLI through browser approval",
|
|
9
|
-
" logout
|
|
11
|
+
" logout Revoke this CLI key and remove the stored local credential",
|
|
10
12
|
" update [--check] Install or check for the latest Hive CLI",
|
|
11
|
-
"
|
|
12
|
-
"
|
|
13
|
-
"
|
|
13
|
+
" skill <action> Install the Hive3 agent skill for Claude Code, Codex or Cursor (hive3 skill install)",
|
|
14
|
+
" whoami Show the authenticated Hive account and the accounts this key can act on",
|
|
15
|
+
" capabilities List the accounts this key can act on and what it may do there",
|
|
16
|
+
" profile <action> Manage profile text, media IDs, access, and builders; add --account <id-or-handle> for an account you help run",
|
|
14
17
|
" upload <file> Upload an allowed image or document and print its storage ID",
|
|
15
|
-
" account <action> Manage account preferences, exports, and deletion
|
|
18
|
+
" account <action> Manage account preferences, exports, linked communities, and deletion cancellation",
|
|
16
19
|
" wallets <action> Manage linked wallet visibility/default selection",
|
|
17
20
|
" nfts <action> Manage public NFT exposure",
|
|
18
|
-
" notifications <action> Manage notifications and notification mutes",
|
|
21
|
+
" notifications <action> Manage notifications, unread count, and notification mutes",
|
|
19
22
|
" comments <action> Manage post comments",
|
|
20
|
-
" communities <action>
|
|
23
|
+
" communities <action> Manage community membership and role-derived admin actions",
|
|
21
24
|
" posts <action> Manage posts",
|
|
22
25
|
" events <action> Manage events",
|
|
23
26
|
" courses <action> Manage courses",
|
|
24
27
|
" content <action> Manage content",
|
|
25
28
|
" quests <action> Manage quests",
|
|
26
29
|
" jobs <action> Manage jobs",
|
|
30
|
+
" search <query> Search accounts, events, courses, content, quests and jobs",
|
|
31
|
+
" broadcasts <action> Draft, test, schedule and send broadcast emails to an account's members",
|
|
32
|
+
" tickets <action> View and update tickets you sell, and list tickets you own",
|
|
33
|
+
" assistant <action> Manage an account's AI assistant and its knowledge documents",
|
|
34
|
+
" credentials <action> View credentials, award custom credentials, list yours and claimable ones",
|
|
35
|
+
"",
|
|
36
|
+
"Options:",
|
|
37
|
+
" -v, --version Print the CLI version",
|
|
38
|
+
" -h, --help Show help",
|
|
27
39
|
"",
|
|
28
|
-
"Resource
|
|
40
|
+
"Resource actions (posts, events, courses, content, quests, jobs):",
|
|
29
41
|
" list [--limit n] [--cursor c] [--owner-type person|community] [--community-id id]",
|
|
42
|
+
" get <id>",
|
|
30
43
|
" create [--title t] [--body b] [--description d] [--content-type t] [--visibility v]",
|
|
31
44
|
" update <id> [--title t] [--body b] [--description d] [--content-type t] [--visibility v]",
|
|
32
|
-
" archive <id>
|
|
45
|
+
" archive <id>",
|
|
46
|
+
"",
|
|
47
|
+
"Account deletion is not available from the CLI; delete your account in the Hive app under Settings.",
|
|
33
48
|
].join("\n");
|
|
34
49
|
}
|
|
35
50
|
|
|
51
|
+
const ACCOUNT_FLAG_LINE = " --account <id-or-handle> Act on an account you own, administer or moderate instead of your own (once, after the action)";
|
|
52
|
+
|
|
53
|
+
/** @type {Record<string, string[]>} */
|
|
54
|
+
const resourceWorkflowLines = {
|
|
55
|
+
posts: [" like <post-id> Toggle your like on a post"],
|
|
56
|
+
events: [
|
|
57
|
+
" participants <event-id> List RSVPs (managers only)",
|
|
58
|
+
" rsvp <event-id> [--enroll true|false] [--file json] RSVP or withdraw your RSVP",
|
|
59
|
+
" approve|deny <event-id> <enrollment-id> Decide an RSVP",
|
|
60
|
+
" attendance <event-id> <enrollment-id> [--attended true|false] [--file json]",
|
|
61
|
+
],
|
|
62
|
+
courses: [
|
|
63
|
+
" enrollments <course-id> List enrollments (managers only)",
|
|
64
|
+
" enroll <course-id> [--enroll true|false] [--file json] Enroll or withdraw",
|
|
65
|
+
" approve|deny <course-id> <account-id> Decide an enrollment",
|
|
66
|
+
" complete <course-id> <lesson-id> Mark a lesson complete",
|
|
67
|
+
],
|
|
68
|
+
content: [],
|
|
69
|
+
quests: [
|
|
70
|
+
" enrollments <quest-id> List enrollments (managers only)",
|
|
71
|
+
" enroll <quest-id> [--enroll true|false] [--file json] Enroll or withdraw",
|
|
72
|
+
" approve|deny <quest-id> <enrollment-id> Decide an enrollment",
|
|
73
|
+
" evidence list <quest-id> [--status s] List submitted evidence",
|
|
74
|
+
" evidence submit <quest-id> --objective-id id [--content text] [--file json]",
|
|
75
|
+
" evidence approve|deny <quest-id> <evidence-id> Decide evidence",
|
|
76
|
+
],
|
|
77
|
+
jobs: [
|
|
78
|
+
" apply <job-id> --file application.json Apply (the file must include a resume)",
|
|
79
|
+
" applications [job-id] List applications (managers only)",
|
|
80
|
+
" status <application-id> --status <pending|reviewed|accepted|rejected>",
|
|
81
|
+
],
|
|
82
|
+
};
|
|
83
|
+
|
|
36
84
|
export function resourceUsage(kind) {
|
|
37
85
|
return [
|
|
38
|
-
`Usage:
|
|
86
|
+
`Usage: hive3 ${kind} <action> [options]`,
|
|
87
|
+
"",
|
|
88
|
+
"Actions:",
|
|
89
|
+
" list [--limit n] [--cursor c] [--owner-type person|community] [--community-id id]",
|
|
90
|
+
" get <id>",
|
|
91
|
+
" create [fields] [--owner-type person|community --community-id id] [--idempotency-key key]",
|
|
92
|
+
" update <id> [fields]",
|
|
93
|
+
" archive <id>",
|
|
94
|
+
...(resourceWorkflowLines[kind] ?? []),
|
|
39
95
|
"",
|
|
40
96
|
"Create/update fields:",
|
|
41
97
|
" --title <text>",
|
|
@@ -44,11 +100,220 @@ export function resourceUsage(kind) {
|
|
|
44
100
|
" --content-type <type>",
|
|
45
101
|
" --image-url <url>",
|
|
46
102
|
" --visibility <public|protected|private>",
|
|
47
|
-
" --file <json>",
|
|
103
|
+
" --file <json> JSON object merged with the flags above",
|
|
48
104
|
"",
|
|
49
|
-
"Create owner fields:",
|
|
105
|
+
"Create owner fields (managed accounts only after `hive3 capabilities` shows them):",
|
|
50
106
|
" --owner-type <person|community>",
|
|
51
107
|
" --community-id <id>",
|
|
52
108
|
" --idempotency-key <key>",
|
|
109
|
+
"",
|
|
110
|
+
"--account is not supported here; use --owner-type/--community-id to create for another account.",
|
|
53
111
|
].join("\n");
|
|
54
112
|
}
|
|
113
|
+
|
|
114
|
+
const ACCOUNT_OPTION_LINES = [
|
|
115
|
+
"Account targeting (where shown): --account <id-or-handle> acts on an account you own, administer or moderate instead of your own.",
|
|
116
|
+
" Reads need communities:read, writes communities:write, plus a live owner/admin/moderator role.",
|
|
117
|
+
];
|
|
118
|
+
|
|
119
|
+
/** @type {Record<string, string[]>} */
|
|
120
|
+
const commandUsageLines = {
|
|
121
|
+
skill: [
|
|
122
|
+
"Usage: hive3 skill <action> [options]",
|
|
123
|
+
"",
|
|
124
|
+
"Actions:",
|
|
125
|
+
" install [--agent claude|codex|cursor] [--project] [--dir <path>] [--force]",
|
|
126
|
+
" Install the bundled Hive3 agent skill so your coding agent knows how to use this CLI",
|
|
127
|
+
" path [--agent a] [--project] [--dir <path>]",
|
|
128
|
+
" Print where `install` would put the skill",
|
|
129
|
+
" show Print the skill (SKILL.md)",
|
|
130
|
+
"",
|
|
131
|
+
"Options:",
|
|
132
|
+
" --agent <name> claude (default), codex or cursor",
|
|
133
|
+
" --project Install for the current directory only instead of your user account",
|
|
134
|
+
" --dir <path> Install into this skills directory (as <path>/hive3); use it for any other agent",
|
|
135
|
+
" --force Replace an existing, different hive3 skill",
|
|
136
|
+
"",
|
|
137
|
+
"Skills directories:",
|
|
138
|
+
" claude ~/.claude/skills/hive3 (--project: ./.claude/skills/hive3)",
|
|
139
|
+
" codex ~/.agents/skills/hive3 (--project: ./.agents/skills/hive3)",
|
|
140
|
+
" cursor ~/.cursor/skills/hive3 (--project: ./.cursor/skills/hive3)",
|
|
141
|
+
"",
|
|
142
|
+
"Restart your agent after installing if it was already running.",
|
|
143
|
+
"Invoke the skill as /hive3 (Claude Code, Cursor) or $hive3 (Codex).",
|
|
144
|
+
],
|
|
145
|
+
logout: [
|
|
146
|
+
"Usage: hive3 logout",
|
|
147
|
+
"",
|
|
148
|
+
"Revokes this CLI key on the server (DELETE /account/keys/current) and removes the stored local credential.",
|
|
149
|
+
"If the server can't be reached, the local credential is still removed and you are told to revoke the key",
|
|
150
|
+
"under Settings → Help & feedback → Developer API keys (https://app.hive3.tech/settings/api-keys).",
|
|
151
|
+
],
|
|
152
|
+
whoami: [
|
|
153
|
+
"Usage: hive3 whoami",
|
|
154
|
+
"",
|
|
155
|
+
"Shows the signed-in account, the key's scopes and the accounts this key can act on. Needs account:read.",
|
|
156
|
+
],
|
|
157
|
+
capabilities: [
|
|
158
|
+
"Usage: hive3 capabilities",
|
|
159
|
+
"",
|
|
160
|
+
"Lists the accounts this key can act on, with your role and the actions allowed on each. Needs communities:read.",
|
|
161
|
+
],
|
|
162
|
+
search: [
|
|
163
|
+
"Usage: hive3 search <query> [--type all|accounts|events|courses|content|quests|jobs] [--limit 1-50] [--cursor c]",
|
|
164
|
+
"",
|
|
165
|
+
"Searches what your account can see. The query is 1-100 characters; quote it or pass several words.",
|
|
166
|
+
"Needs the resources:read scope.",
|
|
167
|
+
],
|
|
168
|
+
broadcasts: [
|
|
169
|
+
"Usage: hive3 broadcasts <action> [options]",
|
|
170
|
+
"",
|
|
171
|
+
"Actions:",
|
|
172
|
+
" list [--account a] [--limit n] [--cursor c]",
|
|
173
|
+
" audience [--account a] Recipient count and when you may next send",
|
|
174
|
+
" get <id>",
|
|
175
|
+
" create --subject <s> --body-text <t> [--body-html h] [--body-mode editor|html] [--hero-image-url u]",
|
|
176
|
+
" [--file json] [--idempotency-key k] [--account a] Creates a draft (flags override --file)",
|
|
177
|
+
" update <id> [--subject s] [--body-text t] [--body-html h] [--body-mode m] [--hero-image-url u | --remove-hero-image] [--file json] Drafts only",
|
|
178
|
+
" test <id> Email the draft to your own address only",
|
|
179
|
+
" send <id> --yes [--at <ISO-8601 date-time>] Email opted-in members now, or schedule it",
|
|
180
|
+
" cancel <id> Return a scheduled broadcast to draft",
|
|
181
|
+
"",
|
|
182
|
+
"send emails every opted-in member (up to 5,000) and can't be undone once it starts, so it requires --yes.",
|
|
183
|
+
"Sending is limited by plan: Honey Bee every 30 days, Swarm 14, Royal 7. Worker Bee can't send.",
|
|
184
|
+
"Needs broadcasts:read / broadcasts:write and an owner, admin or moderator role.",
|
|
185
|
+
...ACCOUNT_OPTION_LINES,
|
|
186
|
+
],
|
|
187
|
+
tickets: [
|
|
188
|
+
"Usage: hive3 tickets <action> [options]",
|
|
189
|
+
"",
|
|
190
|
+
"Actions:",
|
|
191
|
+
" list [--account a] [--limit n] [--cursor c] Tickets an account sells (owners and admins)",
|
|
192
|
+
" get <id>",
|
|
193
|
+
" update <id> [--name n] [--description d] [--amount 10.00] [--currency USD] [--status active|inactive]",
|
|
194
|
+
" mine [--limit n] [--cursor c] Tickets you bought",
|
|
195
|
+
"",
|
|
196
|
+
"Creating tickets, checkout and refunds are not available from the CLI.",
|
|
197
|
+
"Needs tickets:read / tickets:write.",
|
|
198
|
+
...ACCOUNT_OPTION_LINES,
|
|
199
|
+
],
|
|
200
|
+
assistant: [
|
|
201
|
+
"Usage: hive3 assistant <action> [options]",
|
|
202
|
+
"",
|
|
203
|
+
"Actions:",
|
|
204
|
+
" get [--account a]",
|
|
205
|
+
" update [--name n] [--description d] [--avatar-url u] [--visibility public|protected|private] [--account a]",
|
|
206
|
+
" documents [list] [--account a]",
|
|
207
|
+
" documents add <file> [--content-type mime] [--idempotency-key k] [--account a] PDF, DOCX or plain text, up to 5 MB",
|
|
208
|
+
" documents delete <document-id> --confirm <document-id>",
|
|
209
|
+
"",
|
|
210
|
+
"The AI assistant needs a Honey Bee or higher account. Chatting with the assistant is not available from the CLI.",
|
|
211
|
+
"Needs ai:read / ai:write.",
|
|
212
|
+
...ACCOUNT_OPTION_LINES,
|
|
213
|
+
],
|
|
214
|
+
credentials: [
|
|
215
|
+
"Usage: hive3 credentials <action> [options]",
|
|
216
|
+
"",
|
|
217
|
+
"Actions:",
|
|
218
|
+
" list [--account a] [--limit n] [--cursor c] Credentials an account issues",
|
|
219
|
+
" get <id>",
|
|
220
|
+
" award <id> --handles <@a,b,...> --yes Award a custom credential to 1-50 accounts",
|
|
221
|
+
" mine Credentials you hold",
|
|
222
|
+
" claimable [--limit n] [--cursor c] Credentials awarded to you but not yet claimed",
|
|
223
|
+
"",
|
|
224
|
+
"award can't be undone through the CLI, so it requires --yes. Creating, minting, deploying and claiming credentials are not available from the CLI.",
|
|
225
|
+
"Needs credentials:read / credentials:write.",
|
|
226
|
+
...ACCOUNT_OPTION_LINES,
|
|
227
|
+
],
|
|
228
|
+
profile: [
|
|
229
|
+
"Usage: hive3 profile <action> [options]",
|
|
230
|
+
"",
|
|
231
|
+
"Actions:",
|
|
232
|
+
" get",
|
|
233
|
+
" update [--name n] [--username h] [--title t] [--experience e] [--short-description d] [--description d]",
|
|
234
|
+
" [--location l] [--image-storage-id id] [--hero-image-storage-id id] [--attachment-storage-id id]",
|
|
235
|
+
" [--show-collaborator-count true|false] [--custom-collaborator-count n] [--badges a,b] [--socials-json json]",
|
|
236
|
+
" handle <handle> Check whether a handle is available",
|
|
237
|
+
" access --type <open|private|open-subscription|private-subscription> [--subscription-id id]",
|
|
238
|
+
" overview|widgets|welcome-page get",
|
|
239
|
+
" overview|widgets|welcome-page save|import --file <json>",
|
|
240
|
+
" overview|widgets|welcome-page export --file <output-path>",
|
|
241
|
+
"",
|
|
242
|
+
"Options for every action above:",
|
|
243
|
+
ACCOUNT_FLAG_LINE,
|
|
244
|
+
" Reads need the communities:read scope, writes communities:write, plus a live owner/admin/moderator role.",
|
|
245
|
+
" Moderators can't change roles or anything involving payments.",
|
|
246
|
+
],
|
|
247
|
+
upload: [
|
|
248
|
+
"Usage: hive3 upload <file> [--purpose image|document] [--content-type mime]",
|
|
249
|
+
"",
|
|
250
|
+
"Uploads as the signed-in account (--account is not supported); attach the returned storage ID to a profile, resource or workflow payload.",
|
|
251
|
+
"Images: GIF, JPEG, PNG, WebP up to 8 MB. Documents: PDF, DOC, DOCX, Markdown, plain text up to 25 MB.",
|
|
252
|
+
],
|
|
253
|
+
account: [
|
|
254
|
+
"Usage: hive3 account <action> [options]",
|
|
255
|
+
"",
|
|
256
|
+
"Actions:",
|
|
257
|
+
" get",
|
|
258
|
+
" preferences [--theme t] [--muted-notifications a,b]",
|
|
259
|
+
" export Request an export of your account data",
|
|
260
|
+
" linked-communities [list]",
|
|
261
|
+
" linked-communities disconnect <community-id> --confirm <community-id>",
|
|
262
|
+
" deletion cancel Cancel a pending account deletion",
|
|
263
|
+
"",
|
|
264
|
+
"Account deletion can't be requested from the CLI; delete your account in the Hive app under Settings.",
|
|
265
|
+
"Always acts as the signed-in account (--account is not supported).",
|
|
266
|
+
],
|
|
267
|
+
wallets: [
|
|
268
|
+
"Usage: hive3 wallets <action> [options]",
|
|
269
|
+
"",
|
|
270
|
+
"Actions:",
|
|
271
|
+
" list",
|
|
272
|
+
" default <address>",
|
|
273
|
+
" visibility <address> --public true|false",
|
|
274
|
+
" remove <address> --confirm <address>",
|
|
275
|
+
],
|
|
276
|
+
nfts: ["Usage: hive3 nfts visibility --public true|false"],
|
|
277
|
+
notifications: [
|
|
278
|
+
"Usage: hive3 notifications <action> [options]",
|
|
279
|
+
"",
|
|
280
|
+
"Actions:",
|
|
281
|
+
" list [--limit n] [--offset n] [--unread-only]",
|
|
282
|
+
" unread-count",
|
|
283
|
+
" read <id>",
|
|
284
|
+
" read-all",
|
|
285
|
+
" delete <id>",
|
|
286
|
+
" mutes [list]",
|
|
287
|
+
" mutes set --scope <scope> --muted true|false [--scope-id id]",
|
|
288
|
+
],
|
|
289
|
+
comments: [
|
|
290
|
+
"Usage: hive3 comments <action> [options]",
|
|
291
|
+
"",
|
|
292
|
+
"Actions:",
|
|
293
|
+
" list --post-id <id> [--limit n] [--cursor c]",
|
|
294
|
+
" create --post-id <id> --content <text> [--image-url url]",
|
|
295
|
+
" update <id> --content <text>",
|
|
296
|
+
" delete <id>",
|
|
297
|
+
" like <id>",
|
|
298
|
+
],
|
|
299
|
+
communities: [
|
|
300
|
+
"Usage: hive3 communities <action> [options]",
|
|
301
|
+
"",
|
|
302
|
+
"Actions:",
|
|
303
|
+
" join|apply|leave <community-id> [--message text]",
|
|
304
|
+
" applications <community-id> Moderators and above",
|
|
305
|
+
" approve|deny <application-id> Moderators and above",
|
|
306
|
+
" members <community-id> Moderators and above",
|
|
307
|
+
" role <community-id> <account-id> --role <admin|moderator|member> Owners and admins",
|
|
308
|
+
" remove-member <community-id> <account-id> --confirm <account-id> Moderators and above",
|
|
309
|
+
" access <community-id> --type <type> [--subscription-id id]",
|
|
310
|
+
],
|
|
311
|
+
};
|
|
312
|
+
|
|
313
|
+
/** @param {string} command */
|
|
314
|
+
export function commandUsage(command) {
|
|
315
|
+
const lines = commandUsageLines[command];
|
|
316
|
+
return lines ? lines.join("\n") : undefined;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
export const helpCommands = Object.keys(commandUsageLines);
|