> ## 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.

# 에이전트에서 쓰기

> JSON 출력, 컨텍스트 탐색, headless 인증.

CLI는 호출하는 쪽이 사람이 아닐 수 있다는 전제로 만들어졌습니다. 데이터를 돌려주는 방식, 상태를 두는 자리, 로그인시키는 방법에 그 전제가 드러나요.

## JSON 봉투

`--json`을 서브커맨드 앞, 최상위 플래그로 넘기면 모든 명령이 구조화된 봉투를 돌려줍니다.

```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`에는 항상 `data`가, `success: false`에는 항상 `error`가 실려 옵니다. 리스트 명령은 `pagination: { hasMore, nextCursor }`가 data 옆에 따라와요.

## 컨텍스트 탐색

CLI의 상태는 파일 두 개에 있고, 에이전트는 행동 전에 이걸 확인하면 됩니다.

| 경로                         | 내용                                       | 쓰는 주체                                |
| -------------------------- | ---------------------------------------- | ------------------------------------ |
| `~/.gobi/credentials.json` | 인증 토큰                                    | `gobi auth login`                    |
| `.gobi/settings.yaml`      | 이 디렉토리의 `vaultSlug`와 `selectedSpaceSlug` | `gobi vault init`, `gobi space warp` |

```sh theme={null}
gobi --json auth status          # 로그인돼 있나?
cat .gobi/settings.yaml          # 이 프로젝트는 어디에 연결돼 있나?
```

`.gobi/settings.yaml`이 없으면 `gobi vault init`과 `gobi space warp`가 진입점인데, 둘 다 사용자 입력이 필요한 인터랙티브 명령입니다. 에이전트가 조용히 대신 돌리려 하지 말고 사용자에게 넘기세요. `gobi space` 명령은 `--space-slug <slug>`로 설정을 건드리지 않고 일회성 오버라이드를 할 수 있습니다.

## Headless 인증

`gobi auth login`은 URL과 사용자 코드를 stdout에 출력하고 승인될 때까지 폴링합니다. 에이전트는 이걸 백그라운드 작업으로 돌리고, URL을 클릭 가능한 링크로 사용자에게 보여주고, 프로세스 종료를 기다리면 됩니다.

## 대비해둘 에러

`--json`에서 모든 실패는 `success: false`와 사람이 읽을 수 있는 `error`로 옵니다. 에이전트가 평소에 마주치는 건 셋이에요.

* **로그인 안 됨:** 시작 전에 `gobi --json auth status`를 확인하세요. 로그인은 인터랙티브라 사용자에게 넘겨야 합니다.
* **owner 전용 콘텐츠:** `transcript`와 `audio`는 녹음한 사람에게 남습니다. 다른 사람 것을 요청하면 설계상 403이에요. 재시도하지 마세요. 우회 플래그는 없습니다.
* **vault 삭제 거부:** `gobi vault delete`는 vault에 포스트, 멤버, 파일이 남아 있는 동안 거부됩니다.

## Claude Code 스킬

패키지에 `.claude-plugin/` 매니페스트가 들어 있어서, 명령 그룹별 스킬이 같이 설치됩니다.

| 스킬              | 범위                                |
| --------------- | --------------------------------- |
| `gobi-core`     | 인증, 업데이트, 스페이스 목록과 warp           |
| `gobi-space`    | `gobi space …`와 `gobi personal …` |
| `gobi-artifact` | 내 Home의 아티팩트                      |
| `gobi-vault`    | vault init, publish, sync         |
| `gobi-sense`    | activities와 conversations         |