CLI command reference

Use this page to look up a hive3 command, its flags and the scopes it needs. It covers how output, errors and exit codes work, the options shared by many commands, the confirmation flags, and the commands for sign-in, account and profile, uploads, posts and comments, notifications, wallets and NFTs, and communities. Events, courses, content, quests and jobs are on Resources and workflows; search, broadcasts, tickets, the AI assistant and credentials are on Search, broadcasts, tickets, assistant, credentials.

Run hive3 <command> --help for the actions and flags of one command. --help or -h anywhere after a command prints that command's help and never runs it, including logout, whoami, capabilities, login and update. In versions before 0.4, hive3 logout --help signed you out and whoami --help and capabilities --help failed. Help never needs a login.

#How to read this reference

• <id> is a required value, [--flag] is optional. Write values that contain spaces in quotes.
• (0.4+) marks commands and flags that exist only in CLI version 0.4 and later. Unmarked items also exist in 0.3. npm install --global @hive3/cli installs the latest release on npm; if it is older than 0.4, marked items are not available yet. hive3 update --check shows your version.
• The Scopes column lists the scopes the key needs. When a command targets another account with --account, --owner-type community or a community ID, it also needs communities:read for reads or communities:write for writes, plus your current role on that account. See scopes and managed accounts.
• A Read only key covers every :read scope in the tables. Anything that changes data needs Full access or exact scopes. See CLI sign-in and configuration.

#Output and exit codes

Commands that return data print one pretty-printed JSON document on stdout. Successful API responses are wrapped in data; lists add a page object with hasMore and nextCursor. login, logout, update, whoami, capabilities and profile builder export print plain text. Help prints to stdout and exits 0.

Errors go to stderr as one line. API errors have this form:

Hive API error 403 (insufficient_scope): API key does not include the required scope. Required scopes: posts:write.

Mistakes the CLI catches itself print only the message, for example --confirm must exactly match the wallet address. A plan_required error prints Your Hive plan doesn't include API access: the API and CLI need Honey Bee or above. and tells you to upgrade under Settings.

A server-side 401 (for example invalid_api_key) exits with 2, not 1. After a successful interactive command the CLI may print an update notice on stderr; it does not change the exit code. The CLI does not retry a 429 rate_limited; wait and run the command again. See rate limits and errors.

#Shared options

#Pagination

--limit <n> and --cursor <cursor> page through lists. Copy nextCursor from the previous response into --cursor. See pagination.

• Resource lists (posts, events, courses, content, quests, jobs) are newest first, default to 25 items and return at most 100. --limit must be a positive number.
• search (0.4+) takes 1 to 50 (default 20). Broadcasts, tickets and credentials (0.4+) take a whole number from 1 to 100. Comments take a positive number. Notifications use --limit with --offset instead of a cursor.

#Payload files

--file <path> reads a JSON object from a file. A file that is not a JSON object stops the command with <path> must contain a JSON object (or --file must contain a JSON object for resource commands).

• Resource create and update, and workflow commands apply their options left to right and merge top-level fields; a later value replaces an earlier one for the same field. Put --file first to let flags override it, or last to let the file override flags. Nested objects are replaced whole, not merged. --owner-type and --community-id always set owner, replacing any owner in the file.
• Broadcasts create and update (0.4+) read the file first; flags always override it, in any order.
• Profile builders (overview, widgets, welcome-page with save or import) send the whole file as the builder configuration; there is no merge.

#Idempotency

--idempotency-key <key> sends an Idempotency-Key header so a retry of a create does not create a second item. It is accepted by resource create commands, broadcasts create (0.4+) and assistant documents add (0.4+). See idempotency.

#Act on another account

--account <id-or-handle> runs a command against an account where you are owner, admin or moderator, instead of your own. Give it once, after the action name. Giving it twice stops the command with --account may only be given once.

Every other command acts as the signed-in account and rejects --account as an unknown option. To create or list resources for another account, use --owner-type community --community-id <account-id>. To work on members and applications, use the community commands. Moderators cannot change roles or anything involving payments. Run hive3 capabilities first to see which accounts the key can reach.

#Confirmation flags

Some commands refuse to run without an explicit confirmation.

--confirm must repeat the exact ID. For wallets remove, communities remove-member and linked-communities disconnect, place it directly after the ID. --yes is a switch with no value. Other risky commands have no flag: archive, role changes, application and evidence decisions, attendance and replacing builder JSON run immediately. Treat those as confirmation-worthy yourself. See Use Hive3 with AI agents.

Account deletion cannot be requested from the CLI. hive3 account deletion request stops with Account deletion can't be requested from the CLI. Delete your account in the Hive app under Settings. Version 0.3 accepted --confirm DELETE for it; 0.4 and later never do.

#Sign in and session

Each flag of hive3 login is described in CLI sign-in and configuration. hive3 logout, hive3 whoami and hive3 capabilities take no other options.

#Agent skill

hive3 skill installs the Hive3 agent skill that ships inside the CLI. It needs no login and makes no API calls. See Use Hive3 with AI agents for what the skill contains.

--project installs under the current directory instead of your home directory. --dir <path> takes a skills directory for any other agent and cannot be combined with --agent or --project. If a different hive3 skill is already installed, install stops until you add --force; if the same files are there, it reports that and changes nothing.

#Account and profile

profile actions accept --account <id-or-handle>. The account, wallets and nfts commands always act as you.

Boolean values accept true, false, yes, no, 1 and 0. --badges and --muted-notifications take comma-separated lists. A builder save replaces what is stored; run export first to keep a copy. <upload-id> is the ID returned by hive3 upload.

hive3 profile update --account design-guild --name "Design Guild" --short-description "Weekly critiques"
hive3 profile overview export --account design-guild --file overview.json
hive3 profile overview save --account design-guild --file overview.json

#Uploads

Images: GIF, JPEG, PNG and WebP up to 8 MB. Documents: PDF, DOC, DOCX, Markdown and plain text up to 25 MB. The CLI infers the content type from the file extension; pass --content-type for other extensions. --account is not supported; an upload by one account can still be attached to a managed account's profile. Before it sends any file, the CLI checks the upload address the server returns. It refuses the upload unless the address is https (plain http only for a local development server), points at the API host or a Hive3 storage host, and is the Hive3 upload path; redirects are refused and no key is sent with the file. The response is JSON containing the upload ID; put it in --image-storage-id, in a profile flag, or in a --file payload.

hive3 upload ./banner.png --purpose image
hive3 profile update --hero-image-storage-id "<upload-id>"

#Posts and comments

posts uses the common resource actions described in Resources and workflows: list, get <id>, create, update <id> and archive <id>, with the same flags, owner options and --file rules. A post needs a body: --body, or body in the file.

hive3 posts create --body "Office hours move to Thursday." --visibility public
hive3 comments create --post-id "<post-id>" --content "See you there"

#Notifications

--scope is one of system, account, person, community, event, course, job, content or quest. account, person and community need --scope-id. --offset must be zero or greater.

#Wallets and NFTs

The CLI changes only which wallets and NFTs are visible. It never signs, transfers or holds wallet keys.

#Communities

These commands run as you. <community-id> is the account ID of the community. Reads on a community and the actions that need a role require your current role; see the table.

Changing access with communities access leaves pending applications pending; use hive3 profile access --type open --account <id> to switch a private account to open and accept pending applicants.

hive3 communities applications "<community-id>"
hive3 communities approve "<application-id>"
hive3 communities role "<community-id>" "<account-id>" --role moderator