botauth

# botauth

Use `botauth` to securely retrieve API keys, tokens, and credentials from the
user's botauth vault. The desktop app must be running, the vault must be
unlocked, and every `list`, `search`, and `get` request can trigger an approval
prompt.

## When to use

- You need an API key, token, or password to complete a task
- The user asks you to use credentials that already exist in botauth
- You need to fill a `.env` file or config from the user's vault

Do not save new secrets unless the user explicitly asks. `botauth add` opens a
desktop flow for the user to fill in the credential.

## Prerequisites

- `botauth` must be installed and available on `PATH`
- The botauth desktop app must be running
- The vault must be unlocked
- Run `botauth status` first

## Core commands

### Check connection

```bash
botauth status
```

### Search or list secrets

```bash
botauth search "openai"
botauth search "github" --provider github
botauth list
botauth list --provider github
botauth list --tags dev,production
```

### Retrieve a secret in two steps

First get metadata:

```bash
botauth get "OpenAI API Key"
botauth get --id <secret-id>
```

Then fetch the sensitive fields:

```bash
botauth get --id <secret-id> --fields api_key
botauth get --id <secret-id> --fields api_key,client_secret --access-key <key>
```

Reuse `--access-key` inside the same workflow when possible to avoid redundant
approval prompts.

### Ask the user to create a secret

```bash
botauth add
botauth add --app openai --secret-name "Production Key"
```

## Typical workflow

```bash
botauth status
botauth search "openai"
botauth get "OpenAI API Key"
botauth get --id <id> --fields api_key --access-key <access-key>
export OPENAI_API_KEY="<value>"
```

## JSON output

Use `--json` for machine-readable output:

```bash
botauth search "github" --json
botauth get --id <id> --fields token --json
```

## Important notes

- `list`, `search`, `get`, and `add` may show approval prompts in the desktop app
- Sensitive v...

# botauth

Use the `botauth` CLI to retrieve secrets from a local botauth vault with
desktop approval prompts.

## What this skill does

- Searches and lists existing secrets in botauth
- Retrieves secret metadata first, then sensitive fields in a second step
- Encourages minimal secret access and reuse of short-lived access keys
- Defers secret creation to the user through `botauth add`

## Best for

- Codex or Claude workflows that need API keys already stored in botauth
- Agent tasks that must keep humans in the loop for secret access
- Local-first secret retrieval instead of long-lived `.env` files

## Requirements

- `botauth` CLI installed
- botauth desktop app running
- Vault unlocked

## Install the CLI

```bash
npm install -g @botauth/cli
```

## Example workflow

```bash
botauth status
botauth search "openai"
botauth get "OpenAI API Key"
botauth get --id <id> --fields api_key --access-key <access-key>
```

## Files

- `SKILL.md`: agent instructions
- `manifest.yaml`: registry metadata for ClawHub-style publishing