CLI sign-in and configuration

The CLI signs in with a browser approval, the same pattern as many device logins: the terminal shows a code, you confirm it on the Hive3 approval page, and the CLI receives an API key that belongs to your account. This page covers each step of that flow, the permission choices, the files and environment variables the CLI uses, and what to do when something fails.

A CLI key is an ordinary API key owned by the account that approved it. It follows the same scopes, managed-account rules and rate limits as a key you create in the app. Approving a login needs Honey Bee+ or above.

#Sign in with browser approval

1. Run hive3 login

   Start the loginCopy

   hive3 login

   The CLI asks Hive3 for a login request and prints an approval URL and a code. The URL never contains the code.

   Terminal outputCopy

   Open this URL to approve Hive CLI access: https://app.hive3.tech/cli/authorize
   Code: ABCD-EF2G (type it on the approval page)

   It then opens the URL in your default browser, unless you pass --no-open, and waits, polling every 2 seconds.

2. Sign in on the approval page

   If you are not signed in, the page shows Sign in first. Choose a sign-in method, then continue.

3. Enter the code

   Under Enter the code, type the code from your terminal into CLI code. Codes have the form XXXX-XXXX. The field ignores case, spaces and dashes, and codes never contain the characters I, O, 0 or 1. If the page says the code does not match an active CLI login, start a new login from your terminal.

4. Review and approve

   The Approve login card shows the account you approve as, the request name (see --label), the access toggle, and the Granted scopes list. The Approve login button stays disabled until the code you typed matches the request. Select it to approve, or Cancel to refuse.

   If your account is below Honey Bee, the card shows A Honey Bee subscription is required to create API keys. and the button stays disabled.

5. Return to the terminal

   After approval the page says Hive CLI approved. The terminal stores the key and prints:

   Terminal outputCopy

   Hive CLI authenticated as API key hive_sk_…
   Credential stored at /home/you/.config/hive/config.json.

#Timing

#Choose Read only or Full access

When you run hive3 login without --access or --scope, the approval page shows two choices. Read only is selected by default. Your choice decides which scopes the key gets.

Read only grants 8 scopes and Full access grants 17. Neither grants account:destroy. Keys created before the broadcast, ticket, AI and credential scopes existed do not include them; sign in again to get them.

Scopes are necessary but not sufficient. For anything on another account you also need your live role there. See scopes.

#Login options

• --access cannot be combined with --scope. The CLI stops with --access cannot be combined with --scope. Use one permission bundle or exact scopes.
• --scope account:destroy is refused: the server answers Hive API error 400 (invalid_request): scopes must contain supported public API scopes. The CLI never receives permission to delete an account.
• Scope names must be one of the 17 in the table above.
• --api-url and --app-url are for local and staging setups. The server uses an --app-url only when it has the same origin as its own site address. Plain http is accepted only for localhost, 127.0.0.1 and ::1; otherwise the CLI refuses to send credentials over an insecure connection.

hive3 login --access read --label "Reporting script" --no-open
hive3 login --scope posts:read --scope resources:read --label "Read-only sync"

#Where the CLI stores your key

The CLI keeps one credential file named config.json.

The file holds five fields:

{
  "apiBaseUrl": "https://app.hive3.tech/api/v1",
  "apiKey": "hive_sk_…",
  "createdAt": "2026-10-27T18:00:00.000Z",
  "keyPrefix": "hive_sk_…",
  "scopes": ["account:read", "posts:read"]
}

• The key is stored in plain text and protected by file permissions: the directory is created with mode 0700 (an existing directory keeps its permissions) and the file with mode 0600, so only your user can read it.
• The CLI writes the file through a private staging directory and an atomic rename, so no predictable temporary file appears even when HIVE_CONFIG_HOME is a shared directory.
• The key is never printed, logged or placed on a command line. Do not paste the file into chat, tickets or prompts.
• The same directory holds update-check.json, which stores when the CLI last checked npm.
• If the file is not valid JSON the CLI prints Hive CLI config is malformed. Run hive3 login again. If it lacks a key or API URL, it prints Hive CLI config is missing credentials. Run hive3 login again.

#Environment variables

HIVE_API_URL and HIVE_APP_URL are read at login time only. Every later command uses the API URL stored in config.json, so changing HIVE_API_URL afterwards does not redirect an existing key. To use another API URL, sign in again.

#Sign out and revoke a key

hive3 logout

hive3 logout revokes the stored key on the server, prints Revoked the server credential., deletes the local file and prints Removed Hive CLI credential at <path>. It takes no options.

To revoke a key in the app, for example one from a lost laptop:

1. Open the key list

   SettingsHelp & feedbackDeveloper API keysManage API keys opens the page titled API Keys.

2. Find the key

   Under Active keys, CLI keys appear under the name you chose with --label (default Hive CLI) with their prefix and when they were last used.

3. Revoke it

   Choose Revoke on that key. Requests with it return 401 invalid_api_key immediately.

Signing in again replaces the local file but does not revoke the previous key. After you switch from Read only to Full access, revoke the earlier key in the app or run hive3 logout before the new hive3 login.

#Act as a different account

A CLI key belongs to the account that approved it and reaches every account where that account is owner, admin or moderator. To act as a different signed-in user, run hive3 logout, then hive3 login and approve as that user. For accounts you help run, use --account or --owner-type/--community-id instead. See CLI command reference.

#Updates

The CLI checks npm for a newer release at most once every 24 hours, only when stderr is a terminal, CI is not set and HIVE_NO_UPDATE_CHECK is not 1 or true. After a command succeeds it prints on stderr:

Hive CLI update available: 0.4.0 → 0.4.1
Run `hive3 update` to install it.

• hive3 update --check reports the latest version without installing it. If you are current it prints Hive CLI <version> is already the latest version.
• hive3 update looks up the latest version, prints it, and installs exactly that version with npm install --global @hive3/cli@<version>. The version is validated before it reaches npm.
• The check only reads public package metadata from npm. It never sends your Hive credentials and adds no signature check beyond npm's own.

#Troubleshooting

For a failing request, Requests, errors and limits lists every error code.