> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> The docex setup command authenticates via GitHub, provisions a wallet, and returns an API key. Designed for agent-first onboarding with human approval at the payment boundary.

# Setup

> The `docex setup` command is the primary onboarding path. It authenticates via GitHub, provisions a prepaid wallet, and returns a scoped API key. Human approval is only required for the wallet top-up.

## Command

```bash theme={null}
docex setup --use-case "vision analysis for security scanning" --framework auto --top-up 5 --json
```

## Flags

| Flag          | Required | Description                                                |
| ------------- | -------- | ---------------------------------------------------------- |
| `--use-case`  | Yes      | Description of your workflow. Used for workspace labeling. |
| `--framework` | No       | `auto`, `next`, or `node`. Defaults to `auto`.             |
| `--top-up`    | No       | USD wallet recharge amount. Defaults to `5`.               |
| `--base-url`  | No       | API base URL. Defaults to `http://localhost:4000`.         |
| `--json`      | No       | Output machine-readable JSON instead of human text.        |

## Flow

<Steps>
  <Step title="Agent runs setup">
    The agent executes `docex setup --json` and receives a pending setup session with an approval URL.
  </Step>

  <Step title="Human approves">
    The human opens the approval URL, signs in with GitHub, and approves the wallet top-up.
  </Step>

  <Step title="Agent receives credentials">
    The agent polls the setup session. Once approved, it receives `DOCEX_API_KEY` and `DOCEX_BASE_URL`.
  </Step>

  <Step title="Agent wires the app">
    The agent exports the credentials to environment variables and scaffolds the integration.
  </Step>
</Steps>

## Output example

```json theme={null}
{
  "status": "approved",
  "apiKey": "dx_live_xxxxxxxxxxxx",
  "baseUrl": "https://api.docex.dev",
  "walletBalanceUsd": 5.00
}
```

<Warning>
  The API key is shown **once** during setup. Store it immediately in environment variables or a secrets manager.
</Warning>

## Local development

Without Stripe secrets, checkout is mocked and the setup session is approved immediately. This is useful for testing and offline development.

```bash theme={null}
export DOCEX_BASE_URL="http://localhost:4000"
npx docex setup --use-case "local testing" --top-up 5 --json
```