Skip to main content
This walkthrough takes you from zero to a running abadge run in about five minutes.

​
Prerequisites

  • macOS or Linux (x86_64 or arm64)
  • An abadge.io account, or a self-hosted API URL

​
1. Install the CLI

The installer detects your OS and libc, downloads the latest signed CLI release, verifies the SHA-256 checksum, installs to ~/.abadge/bin/abadge, and adds it to your shell profile.

​
2. Authenticate

The CLI starts a device-code flow and opens your browser. Approve the request to attach your CLI to your account. The bearer token is held in daemon memory only — never written to disk.
abadge login does not register any agents. The next step registers the local runtime agent that abadge run uses.

​
3. Set up an organization and profile

If you don’t have an org yet, create one:
Then create (or switch to) a profile:
Server-managed is the simplest storage mode. For zero-knowledge profiles, bootstrap them in the dashboard before adding items.

​
4. Register the CLI’s runtime agent

abadge run needs a local_cli agent to authenticate with. The CLI generates an Ed25519 keypair, uploads the public key, and writes the private key to ~/.abadge/agents/ with 0600 permissions:
The command updates ~/.abadge/config.json’s localAgents.cli automatically. Re-run it any time you want to rotate the keypair.

​
5. Store a secret

The CLI prompts for the value interactively (echo-masked). Server-managed items are encrypted with AES-256-GCM by the API. Note the item ID from the success message. You’ll need it in the next step.

​
6. Grant the CLI agent access

Permissions are explicit: agent + item + capability.
Find the cli-agent-id with abadge agent list (it’s the agent with kind local_cli). The CLI grants target a single item, so they use the legacy capability names — mount_env / mount_file (canonical use) and read_ciphertext / reveal_plaintext (canonical read). mount_env is what abadge run needs to inject the secret as an environment variable.

​
7. Use the secret

Inject the secret as an environment variable into any command:
Under the hood, the CLI:
  1. Mints a short-lived abs_... session for the local_cli agent.
  2. Calls POST /v1/access/{itemId}/use with delivery: env.
  3. Spawns node with OPENAI_API_KEY=<value> in its environment.
The secret lives only in the child’s process memory. It never touches disk and never appears in shell history.

​
What just happened

1

Stored

The secret was encrypted with AES-256-GCM and persisted as ciphertext.
2

Permissioned

A capability grant was recorded against (agent, item, capability). No wildcards, no implicit access.
3

Delivered

The secret was injected into a subprocess env var. It never appeared in your shell history.
4

Audited

Every step — login, agent add, item add, permission create, mount — was appended to the immutable audit log. View it with abadge audit.

​
Remote agent variant

If you want a remote agent (CI runner, cloud worker) to consume the secret over HTTPS instead:
The remote agent enrolls with the bootstrap token (via the SDK or API), then calls POST /v1/access/{itemId}/read for the plaintext. See AbadgeAgentClient for the SDK side.

​
Next steps

Concepts

Understand organizations, profiles, items, agents, and permissions.

CLI reference

Every command, flag, and option.

MCP integration

Use stored secrets from Claude Desktop or other MCP clients.

API reference

The REST API and the TypeScript SDK.

Examples

Runnable end-to-end examples for the SDK, CLI, MCP, and HTTP API.