Use Hive3 with AI agents

Set up the Hive3 command-line tool (hive3) and the Hive3 agent skill on this machine, then sign me in. Documentation: https://docs.hive3.tech/developers

Ground rules:
- Do not change anything in my Hive3 account. This setup only reads.
- Never ask me for an API key and never print or open the CLI's credential file. I sign in through my own browser.
- Hive3 developer access needs a Honey Bee plan or above. If the sign-in page says a Honey Bee subscription is required, tell me and stop.
- If you cannot run shell commands (for example in a chat app), do not pretend. Give me the commands below as a numbered list to run myself, and wait for what they print.

Steps:
1. Run `node --version`. It must be v20 or newer; if it is missing or older, tell me and stop.
2. Run `npm install --global @hive3/cli@latest`.
3. Run `hive3 --version`. It must print 0.4.0 or newer; if not, tell me and stop.
4. Install the Hive3 skill for the agent you are: `hive3 skill install --agent claude` (Claude Code), `hive3 skill install --agent codex` (Codex) or `hive3 skill install --agent cursor` (Cursor). For any other agent, run `hive3 skill install --dir <your skills directory>`. Tell me if I need to start a new session so the skill loads.
5. Run `hive3 login --access read --no-open`. It prints an approval URL and a one-time code, then waits. Start it in the background, or otherwise stream its output, so you can read it while it waits. Show me the URL and the code exactly as printed, ask me to open the URL, sign in, type the code and approve, and wait until the command finishes.
6. Run `hive3 whoami` and `hive3 capabilities`. Summarize for me: the account I signed in as, the scopes of the key, and which accounts it can act on.
7. Tell me this key is read only. For write access later I can ask you to run `hive3 login --access full`, which needs my approval in the browser again. Do not run it unless I ask.

An AI agent that can run shell commands can use the hive3 CLI to manage your Hive3 account: draft posts, review applications, send broadcasts. This page explains what the Hive3 agent skill is and what it contains, how to install it with one command, and how to give an agent only the access it needs so that you stay in control of anything hard to undo.

An agent acts with your key and your live roles. Everything it can do, you could do with the same command. Plan the access first, then install the skill.

#What the agent skill is

An agent skill is a folder of plain-text instructions that an AI agent loads when a task matches it. The Hive3 skill, named hive3, teaches an agent to use the CLI safely. It is not a program and holds no credentials. The agent still runs hive3 on your machine, with your stored key.

The skill ships inside the CLI package (version 0.4.0 and later), so there is nothing else to download. hive3 skill install copies it into your agent's skills directory. It contains two files:

SKILL.md contains these sections: Start Safely, Permission Rules, Identity And Capability Checks, Resource Commands, Account, Social, And Community Commands, Broadcasts, Tickets, Assistant, And Credentials, Workflow Commands, Uploads And JSON Files, Exclusions, and Reporting. Print it any time with hive3 skill show.

#What the skill tells the agent to do

• Check the CLI with hive3 --help, and ask you to install it if it is missing. Run hive3 whoami before account or resource work.
• If the CLI is not signed in, ask you to run hive3 login. The agent should run it only when you asked it to connect the CLI, and you approve in the browser.
• Run hive3 capabilities before acting on any account other than yours. If only your own account is listed, report that no managed-account commands are available.
• Never ask you to paste a key into chat, never create or use community-owned keys, and never print stored keys, config file contents, bearer tokens or private upload URLs.
• Ask for explicit confirmation before 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. Never add --yes or --confirm on its own initiative; show you the target ID and the effect first.
• On insufficient_scope, explain which scope is missing and suggest hive3 login --scope …. On forbidden, explain that your live role no longer allows it. On plan_required, tell you the API needs Honey Bee or above and do not retry in a loop. On a 429, stop and report.
• Stay inside the exclusions: no wallet custody or signing, payment capture, credential minting or claiming, private messages, internal administration tools, community-owned keys or hard deletion of accounts.
• Finish by reporting which account was used, which managed account was targeted, what changed with the returned IDs, and any missing permission.

#Install the skill

1. Install and sign in to the CLI first

   Install the CLI and sign in yourself in your own terminal, or let your agent do it with the banner above. See the CLI quickstart. For a first agent session, use a Read only key (see Create a key for one agent).

2. Install the skill for your agent

   Run one command and name the agent you use:

   Install the Hive3 skillCopy

   hive3 skill install --agent claude
   hive3 skill install --agent codex
   hive3 skill install --agent cursor

   Without --agent the skill goes to Claude Code's directory. Add --project to install it for the current directory only instead of your whole user account. If an older, different hive3 skill is already there, the command stops and asks you to re-run it with --force; if the same files are already installed it says so and changes nothing.

   Agent	Where hive3 skill install puts it	With --project
   Claude Code	~/.claude/skills/hive3	./.claude/skills/hive3
   Codex	~/.agents/skills/hive3	./.agents/skills/hive3
   Cursor	~/.cursor/skills/hive3	./.cursor/skills/hive3

3. Using another agent

   Any agent that loads skills from a directory works. Pass its skills directory with --dir; the skill is placed in a hive3 folder inside it. --dir cannot be combined with --agent or --project.

   Install into a skills directory you chooseCopy

   hive3 skill install --dir ~/my-agent/skills
   hive3 skill path --dir ~/my-agent/skills

   hive3 skill path takes the same options and prints where install would put the skill without writing anything. The skills directory is defined by your agent, not by Hive3; check its documentation for the current location.

4. Start a new session and check

   Restart the agent if it was running, so it reloads skills. Invoke the skill as /hive3 in Claude Code and Cursor or $hive3 in Codex, or just ask the agent to use Hive3. Ask it to run hive3 whoami: it should follow the skill's start-up checks and report the account and scopes.

If you cannot install the skill, put the rules from A minimal rules block in the agent's project instructions instead. They carry the same safety behavior without the command examples.

#Create a key for one agent

Give every agent its own key. You can then see in the app which key did what, and revoke one without disturbing the others. The CLI keeps one credential per HIVE_CONFIG_HOME directory, so a separate directory per agent gives it a separate key.

1. Choose the least access that works

   Start with Read only. Add write access only for the task at hand. For something narrower, ask for exact scopes. Include account:read, which hive3 whoami needs, and communities:read if the agent should run hive3 capabilities.

   Sign in for an agentCopy

   export HIVE_CONFIG_HOME=~/.config/hive-agents/reporting
   hive3 login --access read --label "Reporting agent" --no-open

   Exact scopes instead of a bundleCopy

   hive3 login --scope account:read --scope communities:read --scope resources:read --label "Event checker" --no-open

2. Approve the code yourself

   Open the printed URL and type the code from your terminal on the approval page. Check the name and scopes in Granted scopes, then select Approve login. See CLI sign-in and configuration.

3. Run the agent with the same directory

   Start the agent with HIVE_CONFIG_HOME set to the directory you used, so its hive3 commands pick up that key and not your personal one. Confirm with hive3 whoami that the scopes are what you intended.

Keys last 90 days. A key in config.json is readable by anything that runs as your user, including the agent, so choose scopes for what you would accept the agent doing on its worst day.

#Confirm before risky actions

Some commands have a built-in guard, and many do not. The guard is a speed bump for a person, not an authorization: a program that can type --yes can type it without asking. The protection that holds is a narrow key plus a human who approves the exact action.

Before any of these, require the agent to show you the target ID, the account it belongs to and the effect, and wait for your answer. For a broadcast, also have it run hive3 broadcasts test <id> and hive3 broadcasts audience, and show the subject, the audience and the schedule. See the full list of guards under Confirmation flags.

#Review payloads before they run

• Read every --file payload the agent wrote before it runs. Check owner, visibility, autoEnroll, eventSlots and subscriptionId, and any list of handles. Resource and workflow commands apply flags and the file in the order given, so a flag placed after --file silently overrides it.
• Keep personal data out of the transcript. events participants, courses enrollments, quests enrollments and jobs applications include people's primary email addresses when you manage the resource. Tell the agent to summarize instead of quoting them.
• Watch for spending. Creating a quest uses a quest credit of the owning account, and sends and edits by an agent count against your plan's limits like your own.

#Operating rules

• Never paste a key into a prompt, chat, issue or commit. The CLI never prints the key; do not have the agent read config.json.
• Never run hive3 login unattended. A login needs a person to open the approval page and type the code from their own terminal. Do not approve a code that an agent, a script or another person produced for you.
• No unattended CI with this key. The CLI reads only its credential file; there is no environment variable for a key. For jobs without a person, call the API with a key created in the app.
• Check managed-account scope. Run hive3 capabilities and tell the agent which accounts it may touch. Access follows your live role, and it disappears if your role changes. If only your own account is listed, managed-account commands will not work.
• Respect rate limits. Hive3 limits requests per account, and some actions have their own budgets, such as RSVPs (10 per minute, 100 per day) and broadcast sends (by plan). The CLI does not retry a 429. Tell the agent to stop and report instead of looping. See rate limits.
• Account deletion is not possible from the CLI. hive3 account deletion cancel only cancels a pending deletion.

#Revoke an agent's key

Revoke immediately if a key may have leaked, an agent misbehaved, or a task is over.

1. Revoke in the app

   Open SettingsHelp & feedbackDeveloper API keysManage API keys, find the key by the name you gave it under Active keys, and choose Revoke. The key stops working at once.

2. Clear the local file

   Run hive3 logout with the same HIVE_CONFIG_HOME. It tries to revoke the key and removes the file. If the key is already revoked it prints a warning and still deletes the file.

#A minimal rules block

If you cannot install the skill, add rules like these to your agent's project instructions. They mirror the skill's safety behavior.

Use the hive3 CLI for Hive3 work. Run `hive3 whoami` before account work and
`hive3 capabilities` before acting on any account other than the user's own.
Run `hive3 <command> --help` for exact flags.
Never ask for, print or store API keys. Never run `hive3 login` unless the user asked.
Before archive, role changes, member removal, application/RSVP/evidence decisions,
attendance, wallet removal, broadcasts, credential awards, or replacing builder JSON,
show the target ID and effect and wait for the user's approval.
Never add --yes or --confirm on your own. Show --file payloads before running them.
Do not repeat people's email addresses from participant or application lists.
On insufficient_scope, forbidden, plan_required or a 429, stop and report.
Report which account was used, what changed, and the returned IDs.