AI OS CLI for Claude Codeand any AI agent
The AI OS CLI connects you to the same platform from the command line. It is the same 16 tools, so you or your agent can reach your folder, the catalog, the blueprints and the guides without opening a chat.
What is the AI OS CLI
The AI OS CLI is the same 16 tools as commands. You install it once, and then either you or your agent can run them.
It is the only surface that works with no AI open at all, which is what you want when you are setting up several folders, or checking one before an agent sees it.
It is the same software as the MCP server, in the same package, reading the same list of tools. Installing one gives you both.
What you can ask for
Once it is connected you talk to your agent normally. Each of these runs a tool from the list further down.
“Audit my AI OS.”
os_audit
“What is wrong with my CLAUDE.md?”
os_audit, context_read
“My agent keeps losing my voice. Fix it.”
blueprint_get, context_write
“Set up an AI OS here and interview me for it.”
os_init, blueprint_get
“Is there a skill for writing newsletters?”
skills_search
“What actually goes in a context file?”
docs_search
“Which tier am I on, and what would Pro add?”
whoami, upgrade_info
“Check nothing in my folder is stale.”
os_audit
All of your AI OS, from the command line
16 commands, grouped by what they touch. 3 of them cover every skill in the catalog, rather than 1 command per skill, which is what keeps it manageable as the catalog grows.
Audit
Grades your folder and tells you what to fix, worst first. Every finding says what to do next.
Context
Reads and writes the files holding who you are, how you sound, and what you sell.
Blueprints
The method and a template for every file, so what gets written follows your method.
Skills
Searches the catalog and installs one into your AI OS.
Guides
Answers come from the guides published here, not from memory.
Account
Your tier, your allowance, and what the next tier adds.
Every command, and what it is for
All 16. The command is the tool name with dashes instead of underscores, so `os_audit` is `aios-cli os-audit`. Add --help to any of them to see what it takes.
| Tool | What it is for | Where it runs | Your files |
|---|---|---|---|
| os_audit | Tells you what is wrong with your AI OS and what to fix first. Run this before anything else, and before you take anyone's advice about your setup. | Your machine | Reads |
| os_init | Starts a new AI OS in a folder, so your agent has somewhere to put what it learns about you. It writes empty templates on purpose and never touches a file that is already there. | Your machine | Adds |
| os_validate | Confirms your files can actually be read by an agent. Front matter that opens and never closes makes a file invisible rather than broken, so nothing warns you. | Your machine | Reads |
| os_update | Brings your AI OS up to the current release and leaves everything you wrote yourself alone. It compares by hash, so your own edits are reported rather than overwritten. | Your machine | Can replace |
| context_list | Shows the shape of your AI OS at a glance: which context files exist, how much is really in each one, and when it was last touched. | Your machine | Reads |
| context_read | Opens one file in full, so a rewrite builds on what you already said instead of replacing it with a guess. | Your machine | Reads |
| context_write | Saves what your agent learned about you into the file that holds it. A new file is written straight away. Replacing one that already has content asks you first. | Your machine | Can replace |
| blueprint_list | Shows every writing guide and template on the platform, so your agent knows what help exists before it starts writing anything. | Either | Reads |
| blueprint_get | Hands your agent the method for one file, with a template and worked examples. This is what makes it write your way instead of falling back on its own defaults. | Either | Reads |
| skills_search | Finds a ready-made skill for something you want your AI OS to do, so you are not describing it from scratch every time. | Either | Reads |
| skills_get | Shows you what a skill actually adds, before it goes anywhere near your folder. | Either | Reads |
| skills_install | Puts a skill into your AI OS, so every agent that reads the folder can use it. It refuses to replace a skill of the same name unless you say so. | Your machine | Adds |
| docs_search | Answers a question about AI OS from the guides published here, rather than from whatever the model half remembers. | Either | Reads |
| docs_get | Reads one guide in full, for when an excerpt is not enough to act on. | Either | Reads |
| whoami | Says which account you are on, what you can use, and how much of today's allowance is left. Ask for this first when a tool refuses. | Either | Reads |
| upgrade_info | Says what each tier includes and what the next one up would add for you. | Either | Reads |
Where a tool runs is about which server you connected, not about which app you use. The local server runs on your own machine and can see your folder, so it carries all 16. The hosted server runs on ours and has no copy of your folder, so it carries the 8 that do not need one.
That is worth being precise about, because it is easy to get backwards. An agent in the cloud is not cut off from your files. Claude Cowork reaches the folders you attach to it, and writes into them with its own tools, so the hosted 8 are genuinely useful there. What a cloud agent cannot do is start a server on your machine.
Nothing marked your machine is metered, and nothing about your files is sent anywhere. Those tools work signed out and offline, which is why the audit costs nothing and always will.
AI OS comes in 3 tiers: AI OS Starter, AI OS Pro and AI OS Max. Every tool listed here is available on AI OS Starter today. What a paid tier adds is the depth of the answer rather than a longer list of tools.
MCP or the CLI
Both come from the same install and both read one list of tools, so neither can have a tool the other is missing. That is tested rather than intended: the same audit run through both returns a byte for byte identical answer. What changes is when you pay for it, and who does the typing.
What each one costs you
The same 16 tools either way. They differ in when you pay for them.
| MCP server | CLI | |
|---|---|---|
| Loaded every turn | 3,315 tokens | 97 tokens |
| Loaded when your AI OS comes up | Nothing more | 1,595 more, once |
| Tools | 16 | 16 |
| With AIOS_READ_ONLY=1 | 2,364 tokens, 12 tools | The same 12 |
| Works on the web and on your phone | Yes, through the hosted server, with 8 tools | No. There is no command line there |
| Works with no AI open at all | No. MCP is how an agent reaches a tool | Yes. This is the only surface that does |
| You start it by | Asking for something in your own words | Typing a command |
An MCP server sends its full tool list to the model on every turn, whether your AI OS comes up or not. That is the price of being connected at all, before you ask for anything. The CLI costs nothing until it is called: what sits in the conversation is 1 line describing it, and the rest arrives only when your agent reaches for it.
Over 20 turns where your AI OS comes up once, that is 66,300 tokens against 3,535. When your AI OS is most of the conversation, the gap closes and the server is the better experience, because you ask in plain language instead of remembering commands.
Most of the 3,315 is not something anyone can write away. It is the protocol writing out 16 tools as JSON Schema, and any server with this many tools pays roughly the same. Turn it off on the days you are not using it, and every client has a way to do that.
The number stays flat as the catalog grows, because a skill is fetched when your agent asks for one rather than shipped when it connects. A server with 1 tool per skill would pass 50,000 tokens inside a year, and there would be no way back from it.
Every number here came from a real handshake against this build, counted with a tokeniser rather than estimated from the length of the text.
What each one is like to use
| What you are doing | With MCP | With the CLI |
|---|---|---|
| Auditing a folder before you trust it | You ask your agent to audit your AI OS. It reads the report back to you and offers to fix the first thing it found. | You run aios-cli os-audit and read the report yourself. This is the one you want when you are checking several folders, or checking one before an agent has ever seen it. |
| Fixing a voice file that is wrong | Your agent fetches the voice blueprint, interviews you, and writes the file, all inside the conversation. | You fetch the blueprint and write the file yourself, or you ask an agent that can run a command to do it for you. |
| Installing a skill | You say what you want your AI OS to do, and your agent searches the catalog and installs it. | You run aios-cli skills-search, then aios-cli skills-install. |
| Setting up a second AI OS | You open a conversation in that folder and ask. | You run aios-cli os-init and move on. Faster when you are doing several. |
| Proving they really are the same thing | The tool list your client receives. | aios-cli schema os-audit prints the exact schema an MCP client is sent, so you can compare them yourself. |
Use MCP as the default. It is the one that lets you ask for something in your own words and have it done, which is the point of having an AI OS at all.
Reach for the CLI when there is no conversation to have. You are setting up several folders, or you want to check one before an agent has seen it, or you would rather not carry the tool list in every conversation.
Most people end up using both, and both come from the same install.
What the audit catches
Start here, whatever else you do. These are the problems you cannot see from a file listing, which is the reason the audit exists.
A credential in a context file
Pasted in once and read by every agent since. It is reported redacted, never in full.
Placeholders nobody filled in
Your agent has been reading [Your name] as a fact about you for months.
Files that exist and say nothing
An empty voice file is worse than a missing one, because it looks handled.
Context too long to survive
Named with word counts, so you know which file to cut and roughly by how much.
References to files that are gone
Your agent follows them, finds nothing, and carries on without telling you.
Anything stale
Ranked by how load-bearing it is, not just by how old it is.
What it will and will not do
You are pointing an agent at the folder that describes your business, so this is worth reading before you connect anything.
- Your context files never leave your machine. The audit reads them where they are and sends none of them anywhere. Only the rule set travels, and it travels towards you.
- Writes are on by default. A server whose every write needs a flag teaches you to leave that flag on permanently, which looks like protection and is not.
- Anything that could replace work you cannot get back is refused until you confirm it. That is
os_update, and acontext_writeover a file that already has content in it. - Set
AIOS_READ_ONLY=1and the 4 tools that write are never offered at all. Use it when you point an agent you do not fully trust at your folder. - Set
AIOS_AUDIT_LOGto a file and every attempted write is recorded, the ones that were refused as well as the ones that ran. - A credential found in a context file is reported redacted, never in full, so the finding does not become a second copy of the leak.
Tiers
AI OS comes in 3 tiers: AI OS Starter, AI OS Pro and AI OS Max. The tier belongs to your account rather than to anything you installed, so an upgrade changes what your agent can do on its very next request, with nothing to reconnect.
Every tool on this page is available on AI OS Starter. What a paid tier adds is depth rather than a longer list: the fuller set of audit rules, blueprints matched to the kind of business you actually run, and a higher daily allowance for the tools that reach our servers.
The allowances are not published here yet, because the gating is not built yet. Every tool ships as AI OS Starter today. This page gets the numbers the day they are real, rather than a table of figures nothing enforces.
Limits
Local tools are never metered. They read and write your own folder, they never reach our servers, and a limit on them would cost you something while saving us nothing.
Hosted tools count against a daily allowance on your account. Each one carries a weight, so an expensive tool cannot be run 500 times inside a limit sized for cheap ones.
When you run out, the refusal names the time it resets rather than failing silently. Ask your agent for whoami at any point and it tells you what is left.
Settings
None of these are required. They exist for the times you want something other than the default.
| Setting | What it does |
|---|---|
| AIOS_API_KEY | A key, so a machine can sign in without a browser. You normally never set this. aios-cli login handles it and you never see a key. |
| AIOS_SESSION_PATH | Where the sign-in is stored. Defaults to ~/.aios/session.json. |
| AIOS_OS_PATH | Which folder is your AI OS. Defaults to where you are, walking up to the nearest CLAUDE.md, AGENTS.md or context folder the way git finds its root. |
| AIOS_READ_ONLY | Set it to 1 and no tool that writes is offered at all. 12 tools instead of 16. |
| AIOS_AUDIT_LOG | A file to append every attempted write to, allowed and refused alike. |
| AIOS_API_URL | Point it somewhere other than api.aios.guide. For testing. |
| AIOS_REQUEST_TIMEOUT_MS | How long to wait for an answer before giving up. Defaults to 30000. |
What the numbers mean
A command finishes with one of these. Your agent reads them so you do not have to.
| Code | Means | What happened |
|---|---|---|
| 0 | Done | It worked. |
| 2 | Usage | The command was wrong, an argument was missing, or a write was refused because you had not confirmed it. |
| 3 | Not found | The skill, blueprint or guide you asked for does not exist. |
| 4 | Sign in | You are not signed in, or the sign-in is no longer good. |
| 5 | Server | Something went wrong at our end, or the network did. |
| 7 | Allowance | You have used today's allowance for the hosted tools. The message says when it resets. |
| 10 | Not set up | Nothing is set up yet. Run aios-cli login. |
Got any questions left?
AI OS connects through MCP, the Model Context Protocol. MCP is an open standard that gives an AI agent access to tools outside itself.
You add the server once. After that your agent can audit your AI OS, read and write your context files, fetch the writing guide for a file before it writes it, and search the skills catalog, all inside one conversation.
MCP is a standard way for an AI agent to use tools that are not built into it. Think of it as a plugin that works everywhere instead of once per app.
You set up AI OS once. The same connection then runs in Claude, ChatGPT, Cursor, Codex and every other agent on this page.
The CLI is the same 16 tools as shell commands. Both surfaces read one list of tools, so neither can have a tool the other is missing.
You talk to it either way. With MCP your agent calls the tool itself. With the CLI you type `aios-cli os-audit`, or you ask an agent that can run a shell to type it for you.
The CLI adds one thing MCP cannot do. It runs with no agent at all, so you can put it in a script, in CI, or pipe its JSON into jq. Most people use both, and both come from the same install.
Every agent that speaks MCP works, which covers the 11 on this page and anything else that accepts a server URL. What changes is where the agent runs.
- 8 agents run on your machine. Claude Code, Cursor, Codex, Gemini CLI, Antigravity, OpenCode, OpenClaw and Hermes all get 16 tools, because they can read and write your folder. All 8 can also run the CLI.
- 3 agents run in the cloud. Claude Cowork, ChatGPT and Grok Bot connect over the internet, so they lead with the 8 tools that need no filesystem. Cowork can still reach your files through the Claude Desktop app, and Grok Bot can run commands on your machine once you allow that in its settings.
It audits your AI OS and then helps you fix what it finds. Every other tool exists to support that.
- The audit grades your folder and returns what to fix, worst first. Each finding says what to do next.
- The context tools read and write who you are, how you sound, and what you sell.
- The blueprints give your agent the method and a template for each file, so it writes your way instead of its own.
- The skills tools search the catalog and install a skill into your OS.
- The guides tool answers questions from what is published here rather than from memory.
- The account tools report your tier, your allowance and what the next tier adds.
The audit catches the problems you cannot see from a file listing. That is the reason it exists.
- It finds credentials pasted into a context file and read by every agent since. It reports them redacted, never in full.
- It finds template placeholders nobody filled in. Your agent has been reading those as fact.
- It finds files that exist and say nothing. An empty voice file is worse than a missing one, because it looks handled.
- It finds context so long that the end of it is dropped from the window.
- It finds references pointing at files that are not there.
No. You paste the URL and sign in, or you run `aios-cli login` and finish in the browser it opens. Either way you never see a key.
Every local tool works signed out, including the audit. Signing in adds the catalog, the blueprints and the guides.
Grok is the one to check before you start. xAI documents custom MCP connectors at grok.com/connectors, and says you complete whatever sign-in the server asks for there. Grok Bot's own documentation does not cover adding a custom MCP server yet.
The AI OS MCP server and CLI are licensed under the Elastic License 2.0. You can read the source, change it, and use it in your own business on as many machines and projects as you want.
There are 2 things you cannot do. You cannot offer it to other people as a hosted or managed service, and you cannot move, change or work around the tier checks.
That makes it source-available rather than open source, which is a real difference and worth saying plainly. The AI OS Starter Kit is a separate repository with its own license.
No. The audit reads your files on your machine and sends none of them anywhere. Only the rule set is downloaded, and your content never travels the other way.
This is a property of the code rather than a promise on a page. Nothing in the part that reads your files is allowed to make a network request, and a test in the repository enforces that.
All 16 tools cost about 3,659 tokens. That figure is measured from a real connection, not estimated, and the README gives you the command to check it yourself.
The number stays flat as the catalog grows. Skills are fetched when your agent asks for one, rather than shipped at connection time. A server with 1 tool per skill would pass 50,000 tokens within a year.
Nothing to start, and you do not need an account. AI OS Starter includes every local tool with no limit, because those tools never touch our servers.
The hosted tools have a daily allowance. AI OS Pro and AI OS Max raise that allowance, add the fuller audit rules, and add blueprints matched to your business.
Yes. Use it in your own business however you like, on as many machines and projects as you want. It is published on npm and it runs in Docker, so it fits wherever you already work.
Set `AIOS_READ_ONLY=1` to remove every write from the tool list when you point an agent you do not fully trust at your folder. Set `AIOS_AUDIT_LOG` to record every attempted write, the refused ones as well as the ones that ran.
There is also an API, so an agent is never the only way in.