Skip to main content
The Cortex command line is a small tool that runs on your own machine. It signs in as you, the same way Claude Code does, and then does the jobs that are awkward from a browser or a chat: moving an existing folder of markdown notes into a brain, putting a file into a brain’s inbox straight from disk, marking a brain as yours, and emptying a brain when you want to run something again from scratch. Your agent uses it too. When the command line is installed, a connected agent streams files into the inbox through it rather than passing the bytes through the conversation. See ask your agent.

​
Installing it

The command line is published on npm as @oncortex/cli. You need Node 18 or newer and nothing else:
Update it the same way. If your agent finds no cortex on its path and Node is present, it may offer once to run that install for you; it never installs anything unasked.

​
Signing in

1

Copy the connection URL

In Cortex, open any brain’s Connect page, choose the Claude Code tab and copy the URL. It looks like https://api.oncortex.ai/t/your-workspace-id/mcp.
2

Run cortex login

The tool registers itself with your workspace’s sign-in service once, prints a sign-in address, and opens it in a browser when there is one on the machine. Sign in and approve the connection, as you would for any agent. The approval screen names the workspace and shows that the tool will act as you.
3

Paste the address back if the browser is elsewhere

After you approve, the browser is sent to an address on the machine running the tool. If the browser is on that machine, the tool picks it up on its own. If the browser is somewhere else (you are signing in to a server from your laptop, say), that page will not load: copy the address the browser landed on and paste it into the terminal. Pass --no-browser when you know in advance there is no browser.
Once signed in, the login is kept in a settings folder in your home directory, readable only by you, and refreshed on its own. You sign in again only when the connection is revoked on the Connect page, you leave the workspace, or the login sits unused for 90 days. cortex logout forgets the login locally; the connection stays listed on the Connect page until you revoke it there. cortex whoami shows who you are, the inbox counts and the brains you can see, and cortex brains lists the brains alone. If you work in more than one workspace, sign in to each and pick one with --profile <name>.

​
Importing a folder of notes

The command line is the migration tool: it takes a folder of markdown files, the kind Obsidian or a git-backed notes folder holds, and turns it into a brain. Four commands, in order.
1

Analyse the folder

Nothing is sent anywhere. The report says what an import would do: how many files, which are missing a title or a type and what would be filled in, which links resolve and which do not, links that point outside the folder, duplicate names, images and other files that would not be imported, and a proposed folder tree.
2

Create the brain

Creating brains is a workspace admin action. The template is one of blank, personal, company, strategy or client; --personal marks the new brain as yours at the same time. A deleted brain keeps its address, so a slug that belonged to one is refused: choose another.
3

Import

Each file becomes a page at the same path. The front matter is sent exactly as it is, never reordered; a missing title is taken from the first heading or the filename and a missing type from the top-level folder, and both are reported. The import paces itself under the API’s rate limit and saves its progress every 25 pages, so a run that stops part way is safe to run again: pages already written are skipped and the rest are created. A page that changed in the brain since the last run is reported as a conflict rather than overwritten. --dry-run shows the plan without writing. A thousand new pages take about five minutes.
4

Verify

Checks from the brain’s side: every local file is a page and there are no extras, the per-folder counts match, a sample of pages reads back byte for byte, a sample of links resolves, a search by title finds its page, and a dry-run re-import plans no writes. Broken links inside your folder are a warning, not a failure.
What the import does not do: upload images or other non-markdown files (they are listed in the report), carry git history, rewrite links, delete pages for files you removed, or create clients in a partitioned brain. Nothing is ever written into the folder you import from.

​
Marking your brain as yours

This marks a brain as your personal brain: the one your agents write to unless you name another. You need to be the brain’s Owner. One brain per person per workspace carries the mark, so marking a second one moves it. The brain Cortex created for you when you joined is marked already; a brain you created with cortex init is not until you say so, or pass --personal to init. The same mark is the Make this my personal brain button under the brain’s Settings, then General.

​
Putting a file in

The file goes from disk to the brain’s inbox as a source, up to 50 MB, and its text is extracted on arrival. Without --claim, Cortex files it on its next pass under the workspace’s monthly ingestion limit; --skill names the filing skill (ingest-doc, ingest-meeting, ingest-conversation or ingest) so the “is this worth filing” check is skipped. With --claim, the item is held by the agent that ran the command: that agent reads the text, writes the pages and archives the item, and Cortex’s own filer never touches it. --url records where the document lives, so a later version is recognised as a revision; --folder suggests where it should file, and --partition names the client in a partitioned brain.

​
Emptying a brain

Deletes every page and every inbox item, sources included, and puts the blank starter text back on the brain’s instructions page, so the first-document check fires again. The brain itself, its members, credentials, folder structure and settings stay. It is for running a test again from scratch, not for tidying up. You need Admin on the brain, and nothing happens without --yes. Add --keep-instructions to leave the instructions page alone.

​
Is it still being fed?

One line per check, worst first: the session hook, each connected source and credential, the inbox backlog, filing, search coverage, the link counts and, once the brain has a mail address, whether anyone is allowed to forward to it, each with the one thing that fixes it. It is the report described under brain health, read straight from the API. The command exits with code 2 when something is missing or a backlog has built up, so a scheduled job can run it and alert. Add --json for the whole report.

​
Forwarders

The addresses mail may be forwarded to a brain from, as described under your email. forwarders lists them with their state and who added each; add sends the six-digit code to the address (write access on the brain, and an address you can read); verify confirms the code; remove takes one off, with effect from the next delivery, for the member who added it or an Admin. Add --json to forwarders for the rows.

​
Using a service credential instead

Pass --ck with a service credential to run import, verify, upload, health and mail against that credential’s brain without signing in, for example from a scheduled job. A credential is pinned to one brain, so init, connect and personal need a login.

​
Try it

  1. Run cortex analyse on a folder of notes and read the proposed folder tree.
  2. Import it into a new brain, then run cortex verify and check every count matches.
  3. Run cortex whoami and confirm the brain is marked as yours.