Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt

Use this file to discover all available pages before exploring further.

blobhub-worker login is the first-run setup command. It stores your BlobHub API key, pulls your user profile from BlobHub to validate the key, and records the resulting durable identity.

​
Synopsis

blobhub-worker login
No flags.

​
What it does

  1. Prompts for an optional BlobHub API URL (default https://api.blobhub.io/v1; press Enter to accept).
  2. Prompts for your BlobHub API key (read with getpass, so it is not echoed to the terminal).
  3. Calls GET /v1/users/me with the supplied key to validate it and retrieve your user_id, name, and email.
  4. Writes ~/.blobhub-worker/credentials.yaml with mode 0600: 
    api:
  key: bhk_...
  url: https://api.blobhub.io/v1
  5. Writes (or refreshes) ~/.blobhub-worker/identity.yaml: 
    user:
  user_id: usr_01J...
  name: Your Name
  email: you@example.com
  recorded_at: 2026-05-27T12:34:56Z
The command is idempotent — running it again with the same key is a no-op refresh.

​
Identity-change guard

If identity.yaml already records a user_id and the new API key resolves to a different user_id, the command warns and requires explicit confirmation before overwriting. This protects against silently swapping the actor identity by switching credentials.

​
Errors

CodeMeaning
AUTH_INVALIDThe server rejected the API key (401/403 from /v1/users/me).
USER_IDENTITY_MISMATCHThe server’s user_id differs from the previously recorded value, and confirmation was declined.
INSECURE_CREDENTIALS_PERMISSIONScredentials.yaml exists but is world-readable (refused).
Full descriptions: Reference.

​
Recommendation

For production use, create a dedicated service-account user in BlobHub and use that user’s API key for the worker. Some job types (notably Session Agent Harness) classify any post made by the worker’s own user_id as “self” and filter it out — running under a dedicated identity keeps your own posts from being silently dropped. See the Session Agent Harness reference for details.

​
See also