---
name: auvy-cli
description: Use when operating AUVY from a terminal through the auvy CLI — OAuth or API-key auth, vault discovery, ingest, and JSON automation for agents.
---

# AUVY CLI

Use the CLI for terminal automation and Codex shell workflows. Prefer **MCP** when the host can call AUVY tools directly; prefer the **SDK** for application code.

Install from https://github.com/AUVY-AI/auvy-sdk (`bun run setup:local` in the repo root).

## Install

```bash
git clone https://github.com/AUVY-AI/auvy-sdk.git
cd auvy-sdk
bun run setup:local
auvy vault session --json
```

Optional standalone binary: `bun run build` → `./dist/auvy help`

## Auth paths

### Product OAuth (interactive vault sync)

```bash
auvy login
auvy whoami
auvy logout
```

### API key (CI / automation)

```bash
auvy auth login --api-key ak_live_...
auvy auth status
auvy auth mcp      # print MCP connection JSON
auvy auth logout
```

Environment variables (override config): `AUVY_API_KEY`, `AUVY_API_URL`, `AUVY_WORKSPACE_SLUG`, `AUVY_BRAIN_ID`.

Never ask for or print real secrets. Use placeholders in examples.

## Vault commands

| CLI command | MCP equivalent | Purpose |
|-------------|----------------|---------|
| `auvy vault session` | `get_session` | Workspace + brain context |
| `auvy vault document-tree --prefix /` | `vault_browse` | Folder browse |
| `auvy vault search "…"` | `semantic_search` | Semantic search |
| `auvy vault grep "…"` | `grep` | Lexical search |
| `auvy vault read <resource_id>` | `read` | Full document text |
| `auvy vault ingest …` | `ingest` | Text, file, URL, or JSON payload |

### Ingest flags

```bash
auvy vault ingest --file ./notes.md --name "Notes" --path /Research
auvy vault ingest --text - --name "Pasted context"
auvy vault ingest --url https://example.com/spec.pdf --name "Spec"
auvy vault ingest --json-payload '{"key":"value"}' --name "Payload"
```

Optional: `--description`, `--metadata '{"k":"v"}'`, `--owner-type`, `--owner-id`, `--skip-embedding`, `--skip-title-description`.

## JSON output (required for agents)

Always pass `--json` for machine-readable results:

```bash
auvy vault search "refund policy" --json
```

Envelope shape:

```json
{
  "ok": true,
  "schema_version": "1",
  "command": "search",
  "data": {}
}
```

Errors: `ok: false` with stable `error.code` (e.g. `MISSING_API_KEY`, auth failures).

Global flags: `--json`, `--output human|json|jsonl`, `--api-key`, `--api-url`, `--workspace-slug`, `--brain-id`.

## MCP vs CLI

| Prefer MCP when | Prefer CLI when |
|-----------------|-----------------|
| Assistant can call tools in-process | Codex/shell-only environment |
| OAuth via plugin is already wired | You need scripted JSON in CI |
| User is in Cursor / Claude Desktop | Bulk file ingest from local paths |

## Docs

- https://docs.auvy.ai/harness/cli
- https://docs.auvy.ai/harness/vault-discovery
- https://docs.auvy.ai/agent-onboarding/skills/onboarding/SKILL.md