Documentation

The ohapi CLI loads secrets into your application, including an AI agent on this machine. Use the CLI so that you do not paste production credentials into chat tools.

Install the CLI

The CLI is a separate package in the repository. Run npm link in the cli directory. That command puts the ohapi binary on your PATH and uses your working copy of the package. The npm registry has ohapi-cli 0.0.1 only. That version does not have ohapi mcp or ohapi login --device. These need ohapi-cli 0.2.0 or later.

cd cli
npm install
npm link

ohapi --help

To remove the link later, run npm unlink -g ohapi.

Authorize this machine

Run ohapi login. The CLI opens a browser. Press Authorize. The app sends a key to the CLI on a loopback port. You do not see, copy, or paste a key.

ohapi login

ohapi login --api http://localhost:3000   # a local or self-hosted server
ohapi login --port 9898                   # port 9797 is already in use

The CLI stores the key in ~/.ohapi/config.json with mode 0600. The key does not appear in the terminal or in shell history. After login, the CLI shows the account that the key belongs to. If that account is not yours, run ohapi login again. Manage and revoke keys on the Account page. Each ohapi login creates another key.

No browser on this machine (SSH, containers, Codespaces)

Run ohapi login --device. The CLI shows a code and the address of the Connect a device page. Open that page on any device, sign in, type the code, and press Approve. The code expires after 10 minutes. The CLI uses this method automatically in an SSH session, a Codespace or a dev container.

ohapi login --device

Type only a code that your own terminal shows. Do not type a code that another person sent to you. The key goes to the computer that started the login.

A key that you already have (CI)

Create the key on a machine that can reach the server. The server prints the token once. The database stores only the SHA-256 hash of the token. A key has the same access as the user who owns it. The key can reach only the organizations where that user is a member.

npm run key:create -- you@example.com laptop

ohapi login --token - < key.txt   # reads the key from stdin, not from shell history

In CI, do not run login. Set OHAPI_TOKEN in the job secret store. For GitHub Actions without a long-lived secret, create an OIDC trust on the Account page, then exchange the workflow token with POST /api/v1/oidc/github. That exchange returns a one-hour key. Scope a trust to one project so the key cannot read other projects. Revoke keys on the Account page.

Select a project

Every command needs a project and an environment. Commit a .ohapi.json file in the application root. That file holds no secret values.

{ "projectId": "clx1234567890abcdef", "environment": "development" }

List projects that your key can reach with ohapi projects. Or copy the project id from the project Settings tab. That tab can also download a .ohapi.json file.

ohapi projects
ohapi projects --json

Override per command

The CLI resolves each setting in this order:

Command flag
Environment variable
File (.ohapi.json or ~/.ohapi/config.json)

	Flag	Environment variable	File (`.ohapi.json`)
Project	-p, --project	OHAPI_PROJECT_ID	projectId
Environment	-e, --env	OHAPI_ENVIRONMENT	environment
Server	--api	OHAPI_API_URL	— (or `apiUrl` in config)
Token	--token	OHAPI_TOKEN	— (or `hosts.<server>.token` in config)

If you omit the environment, the default is development.

Pull secrets into a file

ohapi pull fetches the environment and writes two files.

ohapi pull                        # .env.local and .env.example
ohapi pull -e production          # different environment
ohapi pull -o .env                # different output file

.env.local: Real secret values. Mode 0600. Do not commit this file. The CLI warns if the file is missing from .gitignore.
.env.example: Each key with value YOUR_VALUE_HERE. Commit this file. Each pull rewrites the file so that keys stay aligned. A new teammate can see required keys without secret values.

Some values cannot be written to a .env file (a value that contains both a ' and a \). The CLI warns and tells you to use ohapi run for those keys.

Inject secrets without a file

ohapi run injects secrets into a child process environment. The command does not write secret values to disk.

ohapi run -- npm run dev
ohapi run -e production -- npm run migrate
ohapi run -- next dev --port 4000     # arguments after -- belong to the child command

Everything after -- is the child command. The child inherits your environment variables. Fetched secrets replace matching variables. The CLI returns the child exit code. When tests fail, ohapi run -- npm test returns a non-zero exit code.

Create or delete a secret (optional)

Use ohapi set to create or update one secret. Use ohapi unset to delete one secret by key. Most local work uses the dashboard or an import instead.

ohapi set API_URL=https://example.com
ohapi set API_URL=https://example.com -e production --confirm-production
ohapi unset API_URL
ohapi unset API_URL -e production --confirm-production

Writes to an environment named production require --confirm-production. If dual control is enabled, the command may return a pending change request. A second admin must approve that request in the dashboard.

Use ohapi from an AI agent (optional)

Use ohapi mcp to give an AI agent a controlled view of your secrets. The command starts a Model Context Protocol server on standard input and output. It uses the key from ohapi login.

claude mcp add ohapi -- ohapi mcp                  # Claude Code
{ "mcpServers": { "ohapi": { "command": "ohapi", "args": ["mcp"] } } }   # Cursor and others

By default the agent can list projects, environments and secret metadata. It cannot read a value. To allow that, add --allow values. Each value read is recorded in the audit log. To give an application its secrets, use ohapi run instead.

A write to production needs --allow production. This option applies the write at once, unless your organization requires approval from a second admin (dual control). A write that waits for approval returns pending. The agent cannot approve it.

The full machine API (HTTP methods, headers, and status codes) is in the repository README.md. Deployment steps are in DEPLOYMENT.md.