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

# Using the CLI from agents

> JSON output, context discovery, and headless auth for agent-driven use.

The CLI assumes the caller might not be a human. That shows up in how it returns data, where it keeps its state, and how it signs you in.

## The JSON envelope

Pass `--json` as a top-level flag, before the subcommand, and every command returns a structured envelope:

```sh theme={null}
gobi --json space list-posts
# {"success": true, "data": [...]}

gobi --json space get-post 99999
# {"success": false, "error": "Post not found"}
```

`success: true` always carries `data`. `success: false` always carries `error`. List endpoints ship pagination alongside the data: `pagination: { hasMore, nextCursor }`.

## Context discovery

The CLI keeps its state in two files an agent can check before acting:

| Path                       | What                                                 | Written by                           |
| -------------------------- | ---------------------------------------------------- | ------------------------------------ |
| `~/.gobi/credentials.json` | Auth tokens                                          | `gobi auth login`                    |
| `.gobi/settings.yaml`      | This directory's `vaultSlug` and `selectedSpaceSlug` | `gobi vault init`, `gobi space warp` |

```sh theme={null}
gobi --json auth status          # are we signed in?
cat .gobi/settings.yaml          # what's this project wired to?
```

If `.gobi/settings.yaml` is missing, `gobi vault init` and `gobi space warp` are the interactive entry points. They need user input, so an agent should hand off to the user instead of driving them silently. Any `gobi space` command also takes `--space-slug <slug>` to override the default without touching settings.

## Headless auth

`gobi auth login` prints a URL and a user code to stdout, then polls until the user authorizes. An agent can run it as a background task, surface the URL as a clickable link, and wait for the process to exit.

## Errors worth planning for

With `--json`, every failure is `success: false` plus a human-readable `error`. Three come up in normal agent use:

* **Not signed in.** Check `gobi --json auth status` before a run; login is interactive, so hand off to the user.
* **Owner-only content.** `transcript` and `audio` belong to the person who recorded. Another member's returns a 403 by design. Don't retry; there is no flag around it.
* **Vault deletion refused.** `gobi vault delete` is rejected while the vault still owns posts, members, or files.

## Claude Code skills

The package ships a `.claude-plugin/` manifest with skills wrapping each command group:

| Skill           | Covers                               |
| --------------- | ------------------------------------ |
| `gobi-core`     | Auth, update, space list and warp    |
| `gobi-space`    | `gobi space …` and `gobi personal …` |
| `gobi-artifact` | Artifacts in your Home               |
| `gobi-vault`    | Vault init, publish, sync            |
| `gobi-sense`    | Activities and conversations         |