The AiAkiv CLI: pin a project to a folder with one command

The AiAkiv CLI is a tool you run as commands in a terminal (CLI means command line tool). It was first published on npm as the package aiakiv on 2026-10-18. The current version is 0.2.1, published on 2026-10-24, and this page describes it (0.2.1 only changes the "what to do next" text of 0.2.0). You don't install it. You run it directly with npx aiakiv ....

Its main job is one thing. It pins an AiAkiv project to a working folder. An AI started in that folder always reads and writes that project, even when you change Main. What folder pinning is and why you'd use it is in Folder binding.

What it does, and what it doesn't

Two commands are for folder pinning.

• bind pins a project to a folder. It writes the same set of files as the console's Download folder ZIP (the connection config, the eight AiAkiv skills, and so on) straight into that folder. Nothing is downloaded as a ZIP.
• doctor checks the folder's config and what your clients have registered, and writes the result to a file.

There are other commands too.

• setup does the account-wide install (the account connection and account-wide skills) for Gemini CLI and Antigravity. It accepts only those two clients. More in setup: the account-wide install for Gemini CLI and Antigravity below.
• console and dashboard run web console work (teams, invitations, projects, switching Main, links, cards) from the terminal and show your account on one screen. This page doesn't cover them. npx aiakiv --help and npx aiakiv console describe show what they can do.

Some things the CLI does not do.

• It does not do the account-wide install for clients other than Gemini CLI and Antigravity. The account connection, plugins and account-wide skills are set up the same way as before. Claude Code uses the plugin marketplace (the account connector or the plugin), Codex uses the Codex install prompt, ChatGPT uses the plugin directory (Connecting ChatGPT), and Cursor uses the install link on the website. Grok connects through its web connector screen. If you give setup another client, such as setup --client claude, it only shows this guidance and does nothing (exit code 2).
• You list and revoke keys in the web console. bind and setup don't clean up keys, except that getting a new key revokes the earlier one. console key only gets an account key for management work.
• It does not keep a sign-in of its own. There is no login command. A key that bind or setup receives is written only to that client's config file. The management account key from console key is written to .aiakiv/console.json in that folder. The CLI keeps tokens or keys nowhere else.

What you need

• Node.js 18.3 or later (it comes with npx). If you don't have it, install it.
  • Windows: winget install OpenJS.NodeJS.LTS
  • macOS: brew install node
  • Linux: your distribution's package (for example sudo apt install nodejs npm) or nvm
• An AiAkiv account, and a browser where you can sign in to the web console (app.aiakiv.com).
• The folder to pin. It must already exist. The CLI does not create it.
• For Claude Code and Cursor, the project must already exist in the web console. For Codex and Gemini CLI it doesn't have to. You can create it on the confirm screen.

The first time, npx asks whether to download the package. Answer y, or run npx -y aiakiv ... from the start.

Commands and options

npx aiakiv bind   --client codex|claude|gemini|cursor --project <name> [--dir <folder>] [--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 <client>[,...]] [--dir <folder>] [--out aiakiv-verification-test.md] [--no-probe]

Per client

The order is the same for every client. Run bind, a person signs in or presses the confirm button, then open the client in that folder and check the save target. What differs is how it authenticates. Claude Code and Cursor use a sign-in (OAuth) connection and don't get a key. Codex and Gemini CLI get a key tied to the project and put it in the config file.

Claude Code

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

The CLI writes .mcp.json in the folder (server name AiAkiv-myproject, address https://mcp.aiakiv.com/mcp?project=myproject), turns this server on in advance in .claude/settings.json, and puts the eight skills in .claude/skills/.

What you do:

1. Run claude in that folder. When it asks whether to trust the folder, say yes. It doesn't ask separately whether to approve the server, because the CLI already turned it on (checked on 2026-10-18 with Claude Code 2.1.302).
2. In /mcp, pick AiAkiv-myproject and sign in through the browser.
3. Ask "check my save target". If binding is folder and the project is myproject, you're done.

Claude Desktop's </> Code reads the same .mcp.json. But opening a folder pinned by the CLI in Desktop hasn't been tried yet. Run claude in a terminal first and finish signing in, then check the save target in Desktop. More in Claude Desktop.

Cursor

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

The CLI writes the same ?project= address to .cursor/mcp.json and puts the eight skills in .agents/skills/. Here's what you do.

1. Open that folder in Cursor.
2. In Cursor Settings (Ctrl+Shift+J), go to Tools & MCP and turn on AiAkiv-myproject. Cursor doesn't connect to a server in a folder, or ask you to sign in, until you turn it on once.
3. Once it's on, Cursor asks you to sign in. Click it and sign in in the browser.
4. In a new chat, ask "check my save target" and see that binding is folder.

If Cursor's global config (~/.cursor/mcp.json) already has an AiAkiv connection that follows Main, the AI may call that one instead. Name the server, as in "check my save target with AiAkiv-myproject", and it goes to the folder connection.

Cursor was checked on 2026-10-24. After we turned on the folder server in Tools & MCP, it connected through sign-in, and naming the server got an answer from the folder connection. The eight skills in .agents/skills/ also showed up in Cursor.

Codex and Gemini CLI

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

For these two the CLI uses an API key tied to the project (Authentication). Instead of issuing a key in the console and pasting it by hand, the CLI gets the key and writes it into the config file for you.

Codex can also pin a folder the sign-in (OAuth) way. But the CLI in its current version (0.2.1) uses only the key way for Codex. For the sign-in way, put the config in by hand. See Method A in §2 of Connecting ChatGPT. Gemini CLI uses only the key way, because its sign-in session doesn't persist.

1. The CLI opens the web console's confirm screen in your browser. If you aren't signed in, you go through the sign-in screen and come back.
2. You press the confirm button. The screen is in Korean for now.
   • If the project exists, you see "CLI 에 키 넘기기" (hand the key to the CLI). Press [예, 넘깁니다] (yes, hand it over).
   • If it doesn't exist, you see "프로젝트를 만들고 키를 넘길까요?" (create the project and hand over the key?). Pick a team (your personal team is picked first) and press [만들고 넘깁니다] (create and hand over).
   • The key itself never appears on either screen.
3. When the browser says to go back to the CLI, you can close the tab. The terminal shows the key id, the team, the server name and the config file path. The key itself is not printed. It is written only to the config file.
4. For Codex, run codex in that folder and say yes when it asks whether to trust the folder. Restart the app. For Gemini, run gemini in that folder.
5. Check with npx aiakiv doctor --dir ./my-work (below). If binding is api-key and the project is myproject, you're done.

Good to know:

• You have 5 minutes to confirm. After that the CLI stops. Run the same command again.
• The key can only read and write. It doesn't have the permission to let an AI do console management (manage). If you need that, issue a key in the web console with "Allow console management by AI (manage)" checked (Authentication).
• A project has only one live key. When you get a new key for the same project, whether from another folder, another client or the web console, that project's previous key is revoked. The confirm screen warns you, and the terminal says how many old keys it revoked. So if you pin the same project to two folders with keys, only the folder that got the key last keeps working. Claude Code and Cursor sign-in connections don't use keys, so this limit doesn't apply to them.
• --no-browser doesn't open a browser and only prints the confirm screen's address. Open it in another browser on this same computer (for example one you're already signed in to). After you press the button, the browser goes back to the CLI on this computer (127.0.0.1), so if you open the address on another device, the CLI never gets the key.
• Codex was checked on 2026-10-18 with 0.1.0 (key connection, reading the seven skills in .agents/skills, binding api-key). There were seven skills then, because aiakiv-dashboard hadn't been added yet. For Gemini CLI, the CLI writing the folder config file has been checked, but using a pinned folder inside Gemini CLI hasn't been tried yet. The account-wide connection from setup has been checked inside Gemini CLI (see the setup section below).

Files created in the folder

• In files that already exist, only the entry with the same name is replaced. Other servers and other settings stay as they are.
• A JSON file with comments or trailing commas is rewritten as standard JSON, and the original is kept as <file>.aiakiv-backup. The original may hold an old key, so check it and delete it. When an entry with the same name is replaced in .codex/config.toml, that file's comments are lost (the values stay). The terminal tells you in both cases.
• The eight skills are aiakiv-onboarding, aiakiv-save-and-recall, aiakiv-graph-query, aiakiv-links, aiakiv-cards, aiakiv-console, aiakiv-contents and aiakiv-dashboard. They come from the public repository github.com/AiAkiv/aiakiv-plugins. A skill folder with the same name is replaced as a whole, and other skills are left alone. If you already have the skills installed account-wide, they're the same content, so nothing breaks. They just show up twice in the list.
• The server name follows the console's rule (AiAkiv-<project name>, see §4 of Connecting ChatGPT). But Claude Code and Cursor don't get a key, so the CLI doesn't know the project id. For a name with letters that aren't English, or a long name, it adds a different short code made from the name instead of the one the console adds. Only the name differs from the console. It works the same. A name of up to 19 English letters is exactly the same as in the console.

setup: the account-wide install for Gemini CLI and Antigravity

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

setup makes an account-wide connection, not a folder one. It accepts only two clients, Gemini CLI and Antigravity. Both connect with an API key only (Authentication), so until now you had to issue a key in the console and paste it in by hand. setup does that for you.

1. The CLI opens a temporary port on 127.0.0.1 on this computer, then opens the web console's "계정 전체 연결용 기억 키 넘기기" screen (hand over the account-wide memory key) in your browser. If you aren't signed in, you go through the sign-in screen and come back.
2. You pick when the key expires and press [예, 넘깁니다] (yes, hand it over). The CLI waits up to 5 minutes and stops if you don't press it in time. An address printed with --no-browser also only works in a browser on the same computer. Both are the same as for bind.
3. The CLI gets one account-wide key that follows Main (the save target) and writes it straight into the account-wide config file of every client you chose. The key itself never shows on screen or in the terminal. The terminal shows only the key id. The server name is AiAkiv and the address is https://mcp.aiakiv.com/mcp. It doesn't clash with a folder connection's AiAkiv-<project>.
4. It writes the eight account-wide skills (skipped with --no-skills).
5. Its last line warns you not to share or commit the config files that hold the key.

Existing files are kept. Only the AiAkiv entry is added or replaced, and other servers and settings stay as they are. If a JSON file has comments, the original is kept as <file>.aiakiv-backup.

What you do:

• Gemini CLI: run gemini in your working folder. The first time you open a folder, it asks whether to trust it. Say yes. In a folder you haven't trusted, Gemini CLI shows even account-wide servers as "Disabled". Then run gemini mcp list in that folder and check that it shows AiAkiv … Connected. You can also check with /mcp inside a Gemini CLI chat.
• Antigravity: if the app was open, restart it, because its config file changed. You can see the server list under Skills & Customizations in the left sidebar, or under More options (...) > MCP Servers in a chat. Antigravity doesn't list MCP tools up front. The agent loads them when it needs them, so if you don't see the tools right away, just ask in a new chat.
• In both clients, ask "check my save target" in a new chat and see that binding is main.

Gemini CLI was checked on 2026-10-24 with Gemini CLI 0.49.0. Gemini CLI read the settings.json that setup wrote, gemini mcp list showed Connected, and asking for the save target with that key gave binding main. Antigravity was checked the same day with Antigravity 2.26.0. After a restart it read the config file and loaded the AiAkiv tools, asking for the save target in a new chat got an answer, and the eight global skills showed up in the app.

Good to know:

• One person has only one live account-wide key. This key isn't tied to a project. It follows Main, and it can only read and write memory. It can't do management work such as creating a team. When you get a new one, the previous account-wide key is revoked. That includes a key you put on another computer and one you got from the web console.
• On the same computer, the key is reused. setup first looks for the key in the AiAkiv entry of the two account-wide files on this computer and tries it. If the key is alive and binding is main, it reuses that key and doesn't open a browser. So running --client gemini and later --client antigravity doesn't revoke anything. If you really need a new key, add --new-key.
• Be careful if you use more than one computer. Another computer has no key to reuse, so you run setup on each computer, and each run gets a new key. That revokes the key on the computer you set up before, and Gemini CLI and Antigravity there start failing with an authentication error (401). In practice, an account-wide connection made with this key works on only one computer at a time. To use the earlier computer again, run setup there again. Then the key on the other computer is revoked instead.
• When it gets a new key, it records only the key id and the key's fingerprint (a short check value made from the key) in ~/.gemini/aiakiv-setup.json. The key itself is not in there.
• The account-wide config files are in your home folder, so .gitignore can't exclude them. Don't share or commit them.
• When it's done, check with npx aiakiv doctor --client gemini,antigravity. The account-wide AiAkiv connection must have binding main. On a 401, run setup again. If binding isn't main, get a new key with --new-key.
• Antigravity has one config file for the whole app, so there is no folder pinning for it. bind --client antigravity is a usage error. Use setup --client antigravity.
• setup doesn't do the account-wide install for other clients. How to do it is in What it does, and what it doesn't above.

Checking with doctor

npx aiakiv doctor --dir ./my-work

doctor looks at the folder's config files, the account-wide config files (~/.cursor/mcp.json, ~/.gemini/settings.json, and Antigravity's ~/.gemini/config/mcp_config.json), the AiAkiv connections registered in your clients (if the claude and codex commands are there), and the folders that hold skills, then writes the result to aiakiv-verification-test.md. It also lists account-wide connections attached alongside the folder connection, so you can spot overlapping ones.

• For key connections (Codex, Gemini CLI), doctor calls the save target check (get_save_target) itself and writes down the team, project and binding. If the key was revoked, the connection is refused (401) and it tells you to run bind again in that folder. When a key connection fails, doctor ends with error code 1.
• For sign-in connections (Claude Code, Cursor), doctor can't check directly because a sign-in is needed. Ask "check my save target" inside the client and see whether binding is folder.
• For the account-wide AiAkiv connection written by setup (Gemini CLI, Antigravity), doctor also calls the check itself. binding must be main. On a 401 it tells you to run setup again, and if binding isn't main, to get a new key with --new-key.
• It also notes whether all eight skills are there. If some are missing, it writes what to do next.

The result file shows only the first 8 characters of a key. Still, there's no need to commit it.

What a good result looks like

If you get main in a folder, you reached a connection that follows Main, not the folder connection. This happens when an account connector, a plugin or setup's account-wide connection is attached too. See When the account connector and a folder connection are both attached and §4 of Connecting ChatGPT.

Letting an AI run it

An AI can run the CLI for you. Ask in the chat like this.

Pin the AiAkiv project myproject to this folder.
Run npx aiakiv bind --client codex --project myproject, and I'll press the confirm button.
When it's done, check with npx aiakiv doctor.

A few rules.

• A person presses the confirm button (bind for Codex and Gemini CLI, and setup) and signs in (Claude Code, Cursor). Don't let the AI work the browser for you.
• If the AI's command time limit is shorter than 5 minutes, the CLI can be cut off while it waits. Then run the same command yourself in a terminal.
• Don't let the AI read the config file that holds the key. The CLI output (key id, server name, file path) is all it needs.

An AI running the CLI for you hasn't been tried yet.

Troubleshooting

• Sign-in doesn't work.

  • Claude Code: pick the server again in /mcp and sign in. Check that the account signed in to the browser is the one that has the project.
  • Codex, Gemini CLI, setup: if no browser opened, open the address shown in the terminal yourself, in a browser on the same computer. If the screen says the request can't be confirmed, run the command again.

• 5 minutes passed, or the confirm code expired. Both bind and setup wait up to 5 minutes and then stop. Run the same command again. A new confirm screen opens.

• The skills couldn't be downloaded. The connection config is already written, so bind doesn't fail. Instead the terminal shows a command to type. Run it in that folder.

  npx -y skills add AiAkiv/aiakiv-plugins -a <agent> -s '*' -y
  

  <agent> is one of claude-code, codex, gemini-cli or cursor. Don't add -g (installs account-wide) or --all (spreads to every agent's folder). Running the same bind again also works. If setup couldn't download them, follow what the terminal shows (for Gemini CLI, a command with -g; for Antigravity, a note to copy the skill folders yourself).

• Gemini CLI shows AiAkiv as "Disabled". You haven't trusted the current folder. In a folder you haven't trusted, Gemini CLI turns off even the account-wide server that setup added. Trust the folder, then run gemini mcp list again and check for AiAkiv … Connected.

• The key was revoked. doctor reports 401, or every tool call fails with an authentication error.

  • A folder pinned with bind: someone got a new key for the same project somewhere else. Run bind again in this folder.
  • The account-wide connection from setup: you ran setup on another computer, or got a new account-wide key in the web console. One person has only one account-wide key, so the key on this computer was revoked. Running setup here again fixes it, but then the key on the other computer is revoked.

• The project name is misspelled.

  • Codex, Gemini CLI: if the project exists but you see "create the project and hand over the key?", the name is wrong. Press [아니요] (no), fix the name, and run it again. If you already created a project with the wrong name, clean it up in the web console.
  • Claude Code, Cursor: the CLI doesn't check whether the project exists. With a wrong name the connection works, but every tool call is blocked. Run bind again with the right name, then delete the server entry made from the wrong name (AiAkiv-<wrong name>) from .mcp.json (for Cursor, .cursor/mcp.json). For Claude Code, also remove it from enabledMcpjsonServers in .claude/settings.json.

• The screen says the key for this project can't be handed over. The project points to a team you're not a member of. Check the project in the web console.

• setup --client claude only shows guidance and stops. That's expected. setup accepts only Gemini CLI and Antigravity. Do the account-wide install for other clients as described in What it does, and what it doesn't.

• bind --client antigravity says it's a usage error. Antigravity has no folder pinning. Use npx aiakiv setup --client antigravity.

• It says there is no setup command. Version 0.1.0 ran. setup exists from 0.2.0. Name the version when you run it, for example npx [email protected] setup --client gemini.

Security

• Don't commit config files that hold a key. These are .codex/config.toml and .gemini/settings.json. If the folder is a git repository or has a .gitignore, the CLI adds them to .gitignore for you. If neither, it only warns you, so add them yourself.
• The account-wide config files written by setup hold a key too. These are ~/.gemini/settings.json and ~/.gemini/config/mcp_config.json, and the key is in plain text. They're in your home folder, so .gitignore can't exclude them. Don't share or commit them. The CLI warns you about this in its last line too. The record file ~/.gemini/aiakiv-setup.json holds only the key id and part of the fingerprint, not the key.
• Don't let an AI read what's in a key file. Don't paste it into chats, issues or documents either.
• The CLI never prints the key on screen, in logs or in error messages. doctor's result file shows only the first 8 characters.
• If a <file>.aiakiv-backup file was created, it may hold an old key. Check it and delete it.
• On macOS and Linux, config files that hold a key are written so only your user can read them.
• If you think a key leaked, revoke it in the web console, or run bind again (for setup's account-wide key, setup --new-key). Getting a new key for the same project revokes the old one. The full minimum is in Key hygiene in Authentication.

Related

• What folder pinning is and how to read binding: Folder binding
• Sign-in connections vs API keys: Authentication
• How ChatGPT and Codex connect, and the server name rule: Connecting ChatGPT
• The Codex account-wide install: Codex install prompt
• When AiAkiv shows up twice in Claude: When the account connector and a folder connection are both attached