---
slug: aiakiv-cli
title: "AiAkiv CLI: 명령 한 줄로 폴더에 프로젝트 고정하기"
description: "npx aiakiv bind 한 줄로 작업 폴더에 AiAkiv 프로젝트를 고정한다. 웹 콘솔의 폴더 ZIP 과 같은 설정 파일과 스킬을 폴더에 직접 쓰고, Codex 와 Gemini CLI 는 브라우저에서 확인 버튼을 누르면 키까지 받아 넣는다. 확인은 npx aiakiv doctor. 전역 설치는 Gemini CLI 와 Antigravity 만 npx aiakiv setup 으로 한다."
lang: ko
---


# 30. AiAkiv CLI: 명령 한 줄로 폴더에 프로젝트 고정하기

AiAkiv CLI 는 터미널에서 명령으로 쓰는 도구다(CLI 는 명령줄 도구라는 뜻이다). npm
패키지 `aiakiv` 로 2026-10-18 에 처음 공개했고, 지금 판은 2026-10-24 에 낸 0.2.1 이다(이
문서는 0.2.1 판 기준이다. 0.2.1 은 0.2.0 에서 "다음 할 일" 안내 문구만 고쳤다). 설치하지 않고 `npx aiakiv ...` 로 바로 실행한다.

주된 일은 하나다. **작업 폴더에 AiAkiv 프로젝트를 고정한다.** 그 폴더에서 실행한 AI 는
Main 을 바꿔도 늘 그 프로젝트로 읽고 쓴다. 폴더 고정이 무엇이고 왜 쓰는지는
[폴더 바인딩](folder-binding)에 있다.

## 무엇을 하고, 무엇을 하지 않나

폴더 고정에 쓰는 명령은 둘이다.

- **`bind`**: 폴더에 프로젝트를 고정한다. 웹 콘솔의 **폴더 ZIP 받기**와 같은 한 벌
  (연결 설정 파일, AiAkiv 스킬 여덟 개 등)을 그 폴더에 직접 쓴다. ZIP 을 내려받지
  않는다.
- **`doctor`**: 폴더 설정과 클라이언트 등록 상태를 확인하고 결과를 파일로 남긴다.

그 밖의 명령도 있다.

- **`setup`**: Gemini CLI 와 Antigravity 의 전역 설치(계정 연결과 전역 스킬)를 한다.
  이 두 클라이언트만 받는다. 자세한 것은 아래
  [setup: Gemini CLI 와 Antigravity 전역 설치](#setup-gemini-cli-와-antigravity-전역-설치)에
  있다.
- **`console`**, **`dashboard`**: 터미널에서 웹 콘솔의 일(팀, 초대, 프로젝트, Main 전환,
  연결, 카드)을 실행하고, 계정 상태를 한 화면으로 본다. 이 문서에서는 다루지 않는다.
  `npx aiakiv --help` 와 `npx aiakiv console describe` 가 할 수 있는 일을 보여 준다.

CLI 가 하지 않는 일도 있다.

- **Gemini CLI 와 Antigravity 가 아닌 클라이언트의 전역 설치는 하지 않는다.** 계정 연결,
  플러그인, 전역 스킬은 지금까지의 방법 그대로 한다. Claude Code 는 플러그인 마켓
  (계정 커넥터나 플러그인), Codex 는 [Codex 설치 프롬프트](codex-install-prompt),
  ChatGPT 는 플러그인 디렉터리([ChatGPT 연결](chatgpt)), Cursor 는 홈페이지의
  설치 링크로 붙인다. Grok 은 웹 커넥터 화면에서 붙인다. `setup --client claude` 처럼 다른
  클라이언트를 주면 이 안내만 보여 주고 아무것도 하지 않는다(종료 코드 2).
- **키 목록 보기와 폐기는 웹 콘솔에서 한다.** `bind` 와 `setup` 은 새 키를 받을 때 앞선 키가
  폐기되는 것 말고는 키를 정리하지 않는다. `console key` 도 관리 작업용 계정 키를 받아
  쓸 뿐이다.
- **로그인 정보를 따로 저장하지 않는다.** CLI 에는 `login` 명령이 없다. `bind` 와 `setup` 이
  받은 키는 그 클라이언트의 설정 파일에만 쓴다. `console key` 가 받는 관리용 계정 키는 그
  폴더의 `.aiakiv/console.json` 에 쓴다. 그 밖에 CLI 가 토큰이나 키를 따로 두는 곳은 없다.

## 준비물

- **Node.js 18.3 이상**(`npx` 가 함께 들어 있다). 없으면 설치한다.
  - Windows: `winget install OpenJS.NodeJS.LTS`
  - macOS: `brew install node`
  - Linux: 배포판 패키지(예: `sudo apt install nodejs npm`) 또는 nvm
- **AiAkiv 계정**과, 웹 콘솔([app.aiakiv.com](https://app.aiakiv.com))에 로그인할 수
  있는 브라우저.
- **고정할 폴더.** 폴더가 이미 있어야 한다. CLI 가 폴더를 만들지는 않는다.
- **Claude Code 와 Cursor 는 프로젝트가 웹 콘솔에 먼저 있어야 한다.** Codex 와 Gemini
  CLI 는 없어도 된다. 확인 화면에서 만들 수 있다.

처음 실행하면 `npx` 가 패키지를 받을지 묻는다. `y` 로 답하거나, 처음부터
`npx -y aiakiv ...` 로 실행한다.

## 명령과 옵션

```bash
npx aiakiv bind   --client codex|claude|gemini|cursor --project <이름> [--dir <폴더>] [--expires-days N] [--no-browser] [--no-skills]
npx aiakiv setup  --client gemini|antigravity[,...] [--expires-days N] [--no-browser] [--no-skills] [--new-key]
npx aiakiv doctor [--client <클라이언트>[,...]] [--dir <폴더>] [--out aiakiv-verification-test.md] [--no-probe]
```

| 옵션 | 뜻 |
|---|---|
| `--client` | bind 에서는 그 폴더에서 쓸 AI 클라이언트. `claude`(Claude Code), `cursor`, `codex`, `gemini`(Gemini CLI) 가운데 하나. setup 에서는 `gemini`, `antigravity` 를 쉼표로 하나나 둘. doctor 에서는 이 다섯을 쉼표로 여럿 줄 수 있고, 빼면 모두 본다 |
| `--project` | 고정할 프로젝트 이름 |
| `--dir` | 고정할 폴더. 빼면 지금 터미널의 폴더 |
| `--expires-days N` | 받는 키를 N 일 뒤 만료되게 한다(bind 는 Codex, Gemini 의 프로젝트 키, setup 은 계정 전체 키). 빼면 기한이 없다(웹 콘솔 발급과 같다) |
| `--no-browser` | 브라우저를 열지 않고 확인 화면 주소만 출력한다(아래 *Codex 와 Gemini CLI*) |
| `--no-skills` | 스킬 여덟 개를 넣지 않는다. 연결 설정은 그대로 쓴다 |
| `--new-key` | setup 이 쓸 수 있는 키가 이미 있어도 새로 받는다(아래 *setup*) |
| `--out` | doctor 결과 파일 이름. 기본은 그 폴더의 `aiakiv-verification-test.md` |
| `--no-probe` | doctor 가 키 연결을 직접 불러 보지 않는다 |

## 클라이언트별 사용법

어느 클라이언트든 순서는 같다. **`bind` 를 실행하고, 사람이 로그인이나 확인 버튼을
누르고, 그 폴더에서 클라이언트를 열어 저장 대상을 확인한다.** 클라이언트마다 다른 것은
인증 방식이다. Claude Code 와 Cursor 는 로그인(OAuth) 연결이라 키를 받지 않고,
Codex 와 Gemini CLI 는 프로젝트에 묶인 키를 받아 설정 파일에 넣는다.

### Claude Code

```bash
npx aiakiv bind --client claude --project myproject --dir ./my-work
```

CLI 가 폴더에 `.mcp.json`(서버 이름 `AiAkiv-myproject`, 주소
`https://mcp.aiakiv.com/mcp?project=myproject`)을 쓰고, `.claude/settings.json` 에 이
서버를 미리 켜 두고, 스킬 여덟 개를 `.claude/skills/` 에 넣는다.

사람이 할 일:

1. 그 폴더에서 `claude` 를 실행한다. 이 폴더를 신뢰하겠냐고 물으면 신뢰한다고 답한다.
   서버를 승인할지는 따로 묻지 않는다. CLI 가 미리 켜 두었기 때문이다(2026-10-18
   Claude Code 2.1.302 에서 확인).
2. `/mcp` 에서 `AiAkiv-myproject` 를 골라 브라우저로 로그인한다.
3. "저장 대상 확인해 줘" 라고 묻는다. `binding` 이 `folder` 이고 프로젝트가
   `myproject` 면 끝이다.

> **Claude Desktop** 의 `</> Code` 도 같은 `.mcp.json` 을 읽는다. 다만 CLI 로 고정한
> 폴더를 Desktop 에서 여는 경우는 아직 확인하지 않았다. 먼저 터미널에서 `claude` 를
> 실행해 로그인까지 끝내 두고, Desktop 에서 저장 대상을 확인한다. 자세한 것은
> [Claude Desktop](desktop-binding)에 있다.

### Cursor

```bash
npx aiakiv bind --client cursor --project myproject --dir ./my-work
```

CLI 가 `.cursor/mcp.json` 에 같은 `?project=` 주소를 쓰고, 스킬 여덟 개를
`.agents/skills/` 에 넣는다. 사람이 할 일은 이렇다.

1. Cursor 로 그 폴더를 연다.
2. Cursor 설정(Ctrl+Shift+J)의 Tools & MCP 화면에서 `AiAkiv-myproject` 를 켠다.
   **Cursor 는 폴더에 든 서버를 사람이 한 번 켜기 전에는 연결하지 않고, 로그인도 묻지
   않는다.**
3. 켜면 로그인하라는 표시가 나온다. 누르고 브라우저에서 로그인한다.
4. 새 채팅에서 "저장 대상 확인해 줘" 라고 물어 `binding` 이 `folder` 인지 본다.

Cursor 전역 설정(`~/.cursor/mcp.json`)에 Main 을 따라가는 `AiAkiv` 연결이 이미 있으면,
AI 가 그쪽을 부를 수 있다. 이때는 "AiAkiv-myproject 로 저장 대상 확인해 줘" 처럼 서버
이름을 지목하면 폴더 연결로 간다.

> Cursor 는 2026-10-24 에 확인했다. Tools & MCP 에서 폴더 서버를 켜자 로그인을 거쳐
> 연결됐고, 서버 이름을 지목하면 폴더 연결로 답했다. `.agents/skills/` 의 스킬 여덟 개도
> Cursor 에 보였다.

### Codex 와 Gemini CLI

```bash
npx aiakiv bind --client codex --project myproject --dir ./my-work
npx aiakiv bind --client gemini --project myproject --dir ./my-work
```

CLI 는 이 둘에 **프로젝트에 묶인 API 키**를 쓴다([연결 인증](auth)). 콘솔에서 키를
발급해 손으로 붙여 넣는 대신, CLI 가 키를 받아 설정 파일에 바로 써 준다.

> Codex 는 로그인(OAuth) 방식으로도 폴더를 고정할 수 있다. 다만 지금 판(0.2.1)의 CLI 는
> Codex 에 키 방식만 쓴다. 로그인 방식으로 하려면 설정을 손으로 넣는다. 방법은
> [ChatGPT 연결](chatgpt) §2 방법 A 에 있다. Gemini CLI 는 로그인 세션이
> 유지되지 않아 키 방식만 쓴다.

1. CLI 가 브라우저로 웹 콘솔의 확인 화면을 연다. 로그인이 안 돼 있으면 로그인 화면을
   거쳐 돌아온다.
2. **사람이 확인 버튼을 누른다.**
   - 프로젝트가 있으면 "CLI 에 키 넘기기" 화면이 나온다. **[예, 넘깁니다]** 를 누른다.
   - 프로젝트가 없으면 "프로젝트를 만들고 키를 넘길까요?" 화면이 나온다. 팀을 고르고
     (개인 팀이 먼저 골라져 있다) **[만들고 넘깁니다]** 를 누른다.
   - 어느 화면에도 키는 나오지 않는다.
3. 브라우저가 "CLI 로 돌아가세요" 를 띄우면 탭을 닫아도 된다. 터미널에 키 번호(키 id),
   팀, 서버 이름, 설정 파일 경로가 나온다. **키 자체는 화면에 출력하지 않고 설정 파일에만
   쓴다.**
4. Codex 는 그 폴더에서 `codex` 를 실행하고, 이 폴더를 신뢰하겠냐고 물으면 신뢰한다고
   답한다. 앱은 다시 시작한다. Gemini 는 그 폴더에서 `gemini` 를 실행한다.
5. `npx aiakiv doctor --dir ./my-work` 로 확인한다(아래). `binding` 이 `api-key` 이고
   프로젝트가 `myproject` 면 끝이다.

알아 둘 것:

- **확인은 5분 안에 해야 한다.** 5분이 지나면 CLI 가 끝나니 같은 명령을 다시 실행한다.
- **키는 읽기와 쓰기만 된다.** AI 에게 콘솔 관리 일을 시키는 권한(`manage`)은 없다.
  그 권한이 필요하면 웹 콘솔에서 **"AI 콘솔 관리 허용 (manage)"** 을 체크해 키를 발급한다
  ([연결 인증](auth)).
- **한 프로젝트에 살아 있는 키는 하나다.** 같은 프로젝트의 키를 새로 받으면, 다른 폴더나
  다른 클라이언트에서 받았든 웹 콘솔에서 발급했든, 그 프로젝트의 이전 키는 폐기된다.
  확인 화면에도 이 경고가 나오고, 폐기했으면 터미널에 "이전 키 N개를 폐기했습니다" 가
  나온다. 그래서 같은 프로젝트를 키로 두 폴더에 고정하면 마지막에 받은 폴더만 동작한다.
  Claude Code 와 Cursor 의 로그인 연결은 키를 쓰지 않아 이 제한과 상관없다.
- **`--no-browser`** 는 브라우저를 열지 않고 확인 화면 주소만 출력한다. 그 주소를 이 PC
  의 다른 브라우저(이미 로그인해 둔 브라우저 등)에서 연다. 확인 버튼을 누르면 브라우저가
  이 PC 안의 CLI(`127.0.0.1`)로 돌아오므로, 다른 기기에서 열면 CLI 가 키를 받지 못한다.
- 확인 화면은 지금 한국어로만 나온다.
- Codex 는 2026-10-18 에 0.1.0 으로 확인했다(키 연결, `.agents/skills` 의 스킬 일곱 개
  읽기, `binding` `api-key`). 그때는 aiakiv-dashboard 가 더해지기 전이라 스킬이 일곱
  개였다. Gemini CLI 는 CLI 가 폴더 설정 파일을 쓰는 것까지 확인했고, 폴더를 고정한
  Gemini CLI 안에서 쓰는 것은 아직 확인하지 않았다. `setup` 의 전역 연결은 Gemini CLI
  안에서 확인했다(아래 *setup* 절).

## 폴더에 생기는 파일

| 파일 | 클라이언트 | 내용 |
|---|---|---|
| `.mcp.json` | Claude Code | 서버 `AiAkiv-<프로젝트>`, 주소 `https://mcp.aiakiv.com/mcp?project=<이름>`(영문 이름이면 프로젝트 이름을 담은 머리글도) |
| `.claude/settings.json` | Claude Code | `enabledMcpjsonServers` 에 서버 이름을 더한다(서버를 미리 켜 둠) |
| `.claude/skills/` | Claude Code | AiAkiv 스킬 여덟 개 |
| `.cursor/mcp.json` | Cursor | `.mcp.json` 과 같은 `?project=` 주소 |
| `.codex/config.toml` | Codex | 서버 `AiAkiv-<프로젝트>`, 주소, `http_headers` 의 `Authorization` 에 키 |
| `.gemini/settings.json` | Gemini CLI | 서버 `AiAkiv-<프로젝트>`, `httpUrl`, `Authorization` 머리글에 키 |
| `.agents/skills/` | Codex, Gemini CLI, Cursor | AiAkiv 스킬 여덟 개 |
| `.gitignore` | Codex, Gemini CLI | 키가 든 설정 파일 경로 한 줄(폴더가 git 저장소이거나 `.gitignore` 가 있을 때) |
| `aiakiv-verification-test.md` | doctor | 확인 결과 |

- **이미 있는 파일은 같은 이름의 항목만 바꾼다.** 다른 서버와 다른 설정은 그대로 둔다.
- 주석이나 끝 쉼표가 있는 JSON 파일은 표준 JSON 으로 다시 쓰면서 원본을
  `<파일>.aiakiv-backup` 으로 남긴다. 원본에 예전 키가 들어 있을 수 있으니 확인한 뒤
  지운다. `.codex/config.toml` 에서 같은 이름의 항목을 바꿀 때는 그 파일의 주석이
  사라진다(값은 남는다). 두 경우 모두 터미널에 알린다.
- **스킬 여덟 개**는 aiakiv-onboarding, aiakiv-save-and-recall, aiakiv-graph-query,
  aiakiv-links, aiakiv-cards, aiakiv-console, aiakiv-contents, aiakiv-dashboard 다. 공개 저장소
  [github.com/AiAkiv/aiakiv-plugins](https://github.com/AiAkiv/aiakiv-plugins) 에서
  받는다. 같은 이름의 스킬 폴더는 통째로 바꾸고, 다른 스킬은 건드리지 않는다. 전역 스킬이
  이미 있어도 내용이 같아 동작에는 문제가 없고, 목록에 두 번 보일 뿐이다.
- **서버 이름**은 콘솔과 같은 규칙(`AiAkiv-<프로젝트 이름>`)으로 짓는다
  ([ChatGPT 연결](chatgpt) §4). 다만 Claude Code 와 Cursor 는 키를 받지 않아
  프로젝트 id 를 모르므로, 영문이 아닌 글자가 든 이름이나 긴 이름이면 콘솔이 붙이는 짧은
  코드 대신 이름에서 만든 다른 코드를 붙인다. 이름이 콘솔과 달라질 뿐 동작은 같다. 영문
  19자 이내의 이름은 콘솔과 똑같다.

## setup: Gemini CLI 와 Antigravity 전역 설치

```bash
npx aiakiv setup --client gemini
npx aiakiv setup --client antigravity
npx aiakiv setup --client gemini,antigravity
```

`setup` 은 폴더가 아니라 **계정 전체 연결**을 만든다. Gemini CLI 와 Antigravity 두
클라이언트만 받는다. 둘은 API 키로만 붙는 클라이언트라([연결 인증](auth)) 콘솔에서
키를 발급해 손으로 붙여 넣어야 했는데, 그 일을 `setup` 이 대신한다.

1. CLI 가 이 PC 의 `127.0.0.1` 에 임시 포트를 열고, 브라우저로 웹 콘솔의 "계정 전체
   연결용 기억 키 넘기기" 화면을 연다. 로그인이 안 돼 있으면 로그인 화면을 거쳐 돌아온다.
2. **사람이 만료 일을 정하고 [예, 넘깁니다] 버튼을 누른다.** CLI 는 최대 5분 기다리고, 그
   안에 누르지 않으면 끝난다. `--no-browser` 로 받은 주소도 같은 PC 의 브라우저에서만 열
   수 있다. 이 두 가지는 `bind` 와 같다.
3. CLI 가 **Main(저장 대상)을 따라가는 계정 전체 키** 하나를 받아, 고른 클라이언트 모두의
   전역 설정 파일에 바로 쓴다. 평문 키는 화면에도 터미널에도 나오지 않고, 터미널에는 키
   번호(키 id)만 나온다. 서버 이름은 `AiAkiv`, 주소는 `https://mcp.aiakiv.com/mcp` 다.
   폴더 연결의 `AiAkiv-<프로젝트>` 와 겹치지 않는다.
4. 전역 스킬 여덟 개를 쓴다(`--no-skills` 면 건너뛴다).
5. 마지막 줄에서 키 평문이 든 설정 파일을 공유하거나 커밋하지 말라고 경고한다.

| 클라이언트 | 전역 설정 파일 | 쓰는 항목 | 전역 스킬 |
|---|---|---|---|
| Gemini CLI | `~/.gemini/settings.json` | `mcpServers.AiAkiv` 의 `httpUrl` 과 `headers.Authorization: Bearer …` | `~/.gemini/skills/` |
| Antigravity | `~/.gemini/config/mcp_config.json` | `mcpServers.AiAkiv` 의 `serverUrl` 과 `headers` | `~/.gemini/config/skills/`(`~/.gemini/antigravity-cli/` 폴더가 있으면 그 아래 `skills/` 에도) |

이미 있는 파일은 지킨다. `AiAkiv` 항목만 더하거나 바꾸고, 다른 서버와 다른 설정은 그대로
둔다. 주석이 있는 JSON 파일이면 원본을 `<파일>.aiakiv-backup` 으로 남긴다.

사람이 할 일:

- **Gemini CLI**: 작업 폴더에서 `gemini` 를 실행한다. 처음 여는 폴더면 이 폴더를
  신뢰하겠냐고 묻는다. 신뢰한다고 답한다. **Gemini CLI 는 신뢰하지 않은 폴더에서는 전역
  서버도 "Disabled" 로 보여 준다.** 그다음 그 폴더에서 `gemini mcp list` 를 실행해
  `AiAkiv … Connected` 가 나오는지 본다. Gemini CLI 대화 안의 `/mcp` 로도 볼 수 있다.
- **Antigravity**: 앱이 켜져 있었다면 설정 파일을 바꿨으니 다시 시작한다. 서버 목록은 왼쪽
  사이드바의 Skills & Customizations 나 대화 화면의 더보기(...) 메뉴 > MCP Servers 에서 볼 수
  있다. Antigravity 는 MCP 도구를 미리 펼쳐 보여 주지 않고 에이전트가 필요할 때 꺼내 쓰므로,
  목록에서 도구가 바로 안 보여도 새 대화에서 물어보면 된다.
- 두 클라이언트 모두 새 대화에서 "저장 대상 확인해 줘" 라고 물어 `binding` 이 `main` 인지
  본다.

> Gemini CLI 는 2026-10-24 에 Gemini CLI 0.49.0 으로 확인했다. setup 이 쓴
> `settings.json` 을 Gemini CLI 가 읽었고, `gemini mcp list` 에 Connected 가 나왔고, 그
> 키로 저장 대상을 물으면 `binding` 이 `main` 이었다. Antigravity 는 같은 날 Antigravity
> 2.26.0 으로 확인했다. 앱을 다시 시작하자 설정 파일을 읽어 AiAkiv 도구를 받았고, 새 대화에서
> 저장 대상을 물으면 답이 왔고, 전역 스킬 여덟 개도 앱에 보였다.

알아 둘 것:

- **계정 전체 키는 한 사람에게 하나만 살아 있다.** 이 키는 프로젝트에 묶이지 않고 Main 을
  따라가며, 기억 읽기와 쓰기만 된다. 팀 만들기 같은 관리 작업은 못 한다. 새로 받으면 앞선
  계정 전체 키는 폐기된다. 다른 PC 에 넣어 둔 키와 웹 콘솔에서 받은 키도 마찬가지다.
- **같은 PC 에서는 키를 다시 쓴다.** `setup` 은 먼저 이 PC 의 두 전역 파일에서 `AiAkiv`
  항목의 키를 찾아 불러 본다. 키가 살아 있고 `binding` 이 `main` 이면 브라우저를 열지 않고
  그 키를 다시 쓴다. 그래서 `--client gemini` 를 한 뒤 `--client antigravity` 를 따로 해도
  앞선 키가 폐기되지 않는다. 꼭 새 키가 필요하면 `--new-key` 를 준다.
- **PC 를 여러 대 쓰면 조심한다.** 다른 PC 에는 다시 쓸 키가 없으니 PC 마다 `setup` 을 따로
  해야 하고, 그때마다 새 키를 받는다. 그러면 앞 PC 의 키가 폐기되어 그 PC 의 Gemini CLI 와
  Antigravity 는 인증 오류(401)가 난다. 계정 전체 키로 붙인 전역 연결은 한 번에 PC 한
  대에서만 동작한다고 보면 된다. 앞 PC 를 다시 쓰려면 그 PC 에서 `setup` 을 다시 하고,
  그러면 이번에는 다른 PC 의 키가 폐기된다.
- 키를 새로 받으면 키 번호(키 id)와 키의 지문(키에서 만든 짧은 확인 값)만
  `~/.gemini/aiakiv-setup.json` 에 적어 둔다. 키 자체는 거기에 없다.
- 전역 설정 파일은 홈 폴더에 있어 `.gitignore` 로 뺄 수 없다. 공유하거나 저장소에 올리지
  않는다.
- 끝나면 `npx aiakiv doctor --client gemini,antigravity` 로 확인한다. 전역 `AiAkiv` 연결은
  `binding` 이 `main` 이어야 한다. 401 이면 `setup` 을 다시 하고, `main` 이 아니면
  `--new-key` 로 다시 받는다.
- Antigravity 는 앱 전체에 설정 파일이 하나라 폴더 고정이 없다. `bind --client antigravity`
  는 사용 오류이고, `setup --client antigravity` 를 쓴다.
- 다른 클라이언트의 전역 설치는 `setup` 으로 하지 않는다. 방법은 위
  [무엇을 하고, 무엇을 하지 않나](#무엇을-하고-무엇을-하지-않나)에 있다.

## doctor 로 확인하기

```bash
npx aiakiv doctor --dir ./my-work
```

doctor 는 그 폴더의 설정 파일, 전역 설정 파일(`~/.cursor/mcp.json`, `~/.gemini/settings.json`,
Antigravity 의 `~/.gemini/config/mcp_config.json`), 클라이언트에 등록된 AiAkiv 연결
(`claude`, `codex` 명령이 있으면), 스킬이 들어 있는 폴더를 살펴 결과를
`aiakiv-verification-test.md` 에 쓴다. 폴더 연결과 함께 붙어 있는 전역 연결도 적어 두어
겹치는 연결을 알아볼 수 있다.

- **키 연결(Codex, Gemini CLI)** 은 doctor 가 저장 대상 확인(`get_save_target`)을 직접
  불러 팀, 프로젝트, `binding` 을 적는다. 키가 폐기됐으면 연결이 거절되고(401), 그
  폴더에서 `bind` 를 다시 하라고 안내한다. 키 연결이 실패하면 doctor 는 오류 코드 1 로
  끝난다.
- **로그인 연결(Claude Code, Cursor)** 은 로그인이 필요해 doctor 가 직접 확인하지 못한다.
  클라이언트 안에서 "저장 대상 확인해 줘" 라고 물어 `binding` 이 `folder` 인지 본다.
- **`setup` 이 쓴 전역 `AiAkiv` 연결(Gemini CLI, Antigravity)** 도 doctor 가 직접 불러
  본다. `binding` 이 `main` 이어야 한다. 401 이면 `setup` 을 다시 하라고, `main` 이 아니면
  `--new-key` 로 다시 받으라고 적는다.
- 스킬 여덟 개가 다 들어 있는지도 적는다. 빠진 것이 있으면 다시 할 일을 적는다.

결과 파일에는 키의 앞 8자만 적힌다. 그래도 저장소에 올릴 필요는 없다.

## 결과 확인 기준

| 연결 | `binding` | 프로젝트 |
|---|---|---|
| `bind` 로 고정한 폴더: Claude Code, Cursor | `folder` | `bind` 에 준 이름 |
| `bind` 로 고정한 폴더: Codex, Gemini CLI | `api-key` | `bind` 에 준 이름 |
| `setup` 으로 만든 전역 연결: Gemini CLI, Antigravity | `main` | 없음(콘솔의 Main 을 따라간다) |

폴더에서 `main` 이 나오면 폴더 연결이 아니라 Main 을 따르는 연결을 부른 것이다. 계정
커넥터나 플러그인, `setup` 의 전역 연결이 함께 붙어 있으면 생긴다.
[계정 커넥터와 폴더 연결이 함께 있을 때](account-connector)와
[ChatGPT 연결](chatgpt) §4 를 본다.

## AI 에게 시키기

CLI 는 AI 가 대신 실행해도 된다. 대화창에 이렇게 부탁하면 된다.

```
이 폴더에 AiAkiv 프로젝트 myproject 를 고정해 줘.
npx aiakiv bind --client codex --project myproject 를 실행하고, 확인 버튼은 내가 누를게.
끝나면 npx aiakiv doctor 로 확인해 줘.
```

다만 지킬 것이 있다.

- **확인 버튼(Codex 와 Gemini CLI 의 `bind`, 그리고 `setup`)과 로그인(Claude Code,
  Cursor)은 사람이 한다.** AI 가 브라우저를 대신 조작하게 하지 않는다.
- **AI 의 명령 실행 시간 제한이 5분보다 짧으면 CLI 가 기다리는 도중에 끊길 수 있다.**
  그때는 사람이 터미널에서 같은 명령을 직접 실행한다.
- **AI 에게 키가 든 설정 파일을 읽히지 않는다.** CLI 출력(키 번호, 서버 이름, 파일 경로)
  만 보여 주면 충분하다.

> AI 가 CLI 를 대신 실행하는 경우는 아직 실제로 돌려 보지 않았다.

## 문제 해결

- **로그인이 안 된다.**
  - Claude Code: `/mcp` 에서 그 서버를 다시 골라 로그인한다. 브라우저에 로그인된 계정이
    그 프로젝트가 있는 계정인지 본다.
  - Codex, Gemini CLI, `setup`: 브라우저가 열리지 않았으면 터미널에 나온 주소를 같은 PC 의
    브라우저에서 직접 연다. "요청을 확인할 수 없습니다" 가 나오면 명령을 다시 실행한다.
- **5분이 지났다, 확인 코드가 만료됐다.** `bind` 와 `setup` 모두 최대 5분 기다리고 끝난다.
  같은 명령을 다시 실행한다. 확인 화면도 새로 열린다.
- **스킬을 받지 못했다.** 연결 설정은 이미 썼으니 `bind` 는 실패로 끝나지 않는다. 대신
  터미널에 직접 칠 명령이 나온다. 그 폴더에서 실행한다.

  ```bash
  npx -y skills add AiAkiv/aiakiv-plugins -a <에이전트> -s '*' -y
  ```

  `<에이전트>` 는 `claude-code`, `codex`, `gemini-cli`, `cursor` 가운데 하나다. 전역에
  넣는 `-g` 와 모든 에이전트 폴더에 퍼뜨리는 `--all` 은 붙이지 않는다. 같은 `bind` 를
  다시 실행해도 된다. `setup` 에서 받지 못했으면 터미널에 나온 안내를 따른다(Gemini CLI 는
  `-g` 가 붙은 명령이, Antigravity 는 스킬 폴더를 직접 복사하라는 안내가 나온다).
- **Gemini CLI 에서 AiAkiv 가 "Disabled" 로 보인다.** 지금 폴더를 신뢰하지 않은 상태다.
  Gemini CLI 는 신뢰하지 않은 폴더에서는 setup 이 넣은 전역 서버도 끈다. 그 폴더를 신뢰한
  뒤 `gemini mcp list` 를 다시 실행해 `AiAkiv … Connected` 를 확인한다.
- **키가 폐기됐다.** doctor 가 401 을 보고하거나, 도구를 부를 때마다 인증 오류가 난다.
  - `bind` 로 고정한 폴더: 같은 프로젝트의 키를 다른 곳에서 새로 받은 경우다. 이 폴더에서
    `bind` 를 다시 한다.
  - `setup` 의 전역 연결: 다른 PC 에서 `setup` 을 했거나, 웹 콘솔에서 계정 전체 키를 새로
    받은 경우다. 계정 전체 키는 한 사람에게 하나라서 이 PC 의 키가 폐기됐다. 이 PC 에서
    `setup` 을 다시 하면 되지만, 그러면 이번에는 다른 PC 의 키가 폐기된다.
- **프로젝트 이름을 잘못 적었다.**
  - Codex, Gemini CLI: 있는 프로젝트인데 "프로젝트를 만들고 키를 넘길까요?" 가 나오면
    이름이 틀린 것이다. **[아니요]** 를 누르고 이름을 고쳐 다시 실행한다. 이미 잘못된
    이름으로 만들었으면 웹 콘솔에서 정리한다.
  - Claude Code, Cursor: CLI 는 프로젝트가 있는지 확인하지 않는다. 틀린 이름이면 연결은
    되지만 도구를 부를 때마다 막힌다. 바른 이름으로 `bind` 를 다시 하고, 틀린 이름으로 생긴
    서버 항목(`AiAkiv-<틀린 이름>`)을 `.mcp.json`(Cursor 는 `.cursor/mcp.json`)에서
    지운다. Claude Code 는 `.claude/settings.json` 의 `enabledMcpjsonServers` 에서도
    지운다.
- **"이 프로젝트의 키는 넘길 수 없습니다" 가 나온다.** 그 프로젝트가 내가 구성원이 아닌
  팀을 가리킨다. 웹 콘솔에서 프로젝트를 확인한다.
- **`setup --client claude` 가 안내만 보여 주고 끝난다.** 정상이다. `setup` 은 Gemini CLI
  와 Antigravity 만 받는다. 다른 클라이언트의 전역 설치는 위
  [무엇을 하고, 무엇을 하지 않나](#무엇을-하고-무엇을-하지-않나)의 방법으로 한다.
- **`bind --client antigravity` 가 사용 오류라고 나온다.** Antigravity 는 폴더 고정이 없다.
  `npx aiakiv setup --client antigravity` 를 쓴다.
- **`setup` 명령이 없다고 나온다.** 0.1.0 이 실행된 것이다. `setup` 은 0.2.0 부터 있다.
  `npx aiakiv@0.2.1 setup --client gemini` 처럼 판을 적어 실행한다.

## 보안

- **키가 든 설정 파일은 저장소에 올리지 않는다.** `.codex/config.toml`,
  `.gemini/settings.json` 이다. 폴더가 git 저장소이거나 `.gitignore` 가 있으면 CLI 가
  `.gitignore` 에 스스로 더한다. 둘 다 아니면 경고만 하니 직접 챙긴다.
- **`setup` 이 쓰는 전역 설정 파일에도 평문 키가 든다.** `~/.gemini/settings.json`,
  `~/.gemini/config/mcp_config.json` 이다. 홈 폴더라 `.gitignore` 로 뺄 수 없으니
  공유하거나 저장소에 올리지 않는다. CLI 도 마지막 줄에서 이렇게 경고한다. 기록 파일
  `~/.gemini/aiakiv-setup.json` 에는 키 번호와 지문 일부만 있고 평문 키는 없다.
- **AI 에게 키 파일 내용을 읽히지 않는다.** 대화창, 이슈, 문서에도 붙여 넣지 않는다.
- CLI 는 키를 화면, 로그, 오류 문구에 내지 않는다. doctor 결과 파일에는 앞 8자만 적는다.
- `<파일>.aiakiv-backup` 이 생겼으면 예전 키가 들어 있을 수 있다. 확인한 뒤 지운다.
- macOS 와 Linux 에서는 키가 든 설정 파일을 그 사용자만 읽을 수 있게 쓴다.
- 키가 새어 나간 것 같으면 웹 콘솔에서 폐기하거나 `bind` 를 다시 한다(`setup` 의 계정
  전체 키는 `setup --new-key`). 같은 프로젝트의 키를 새로 받으면 이전 키는 폐기된다. 키
  보안의 최소선 전체는 [연결 인증의 *키 보안*](auth#키-보안)에 있다.

## 관련 문서

- 폴더 고정이 무엇이고 `binding` 값을 어떻게 읽나: [폴더 바인딩](folder-binding)
- 로그인 연결과 API 키의 차이: [연결 인증](auth)
- ChatGPT 와 Codex 의 연결 방법, 서버 이름 규칙: [ChatGPT 연결](chatgpt)
- Codex 전역 설치: [Codex 설치 프롬프트](codex-install-prompt)
- Claude 에서 AiAkiv 가 두 개로 보일 때: [계정 커넥터와 폴더 연결이 함께 있을 때](account-connector)