Neuralis CLI
Sign in from your own machine, call package routes as yourself, read your agent's skills, and start Claude Code or Codex with your Neuralis skills, tools and context.
neuralis is the command-line client for a Neuralis host. It talks to one host
as one user, in one project, as one agent — and every call it makes is checked
on the server against that identity: the same roles, features and path policies
the member has in the workspace. Nothing it does grants more than the account
already holds.
The same command runs in two places:
- On your own machine, signed in with
neuralis login(OAuth, two browser consents). - Inside the platform, where an activated skill's shell already carries the
stream's session ticket — the first-party skills teach their route calls as
neuralis requestlines, so one call line works in both places.
Install
npm install -g @neuralis/cli # Node.js 22 or newer
neuralis --helpThe platform image ships the same CLI on its PATH for skill shells. Inside an
install folder the operator verbs (neuralis setup, rebuild, upgrade, …)
are handed to that install's own host command unchanged.
Sign in
neuralis login --host https://neuralis.example.com --project <project-id> --agent <agent-id>
neuralis whoami # the identity the SERVER sees — trust this, not local state
neuralis logout # revokes this machine's grants on the host and forgets themLogin opens the browser twice: one consent for the host's package-route API and
one for its MCP server, each an OAuth 2.1 grant bound to that one resource (see
External MCP access). The project and agent you name
are a request, not authority — the consent screen and the server decide, and
whoami reports the result. --no-browser prints the URL instead.
The grants are stored in the user's own configuration directory
($XDG_CONFIG_HOME/neuralis or ~/.config/neuralis; macOS
~/Library/Application Support/neuralis; Windows %APPDATA%\neuralis;
NEURALIS_CLI_HOME overrides it), readable only by that user, and bound to the
host they were issued by — a stored token is never sent anywhere else. Access
tokens renew themselves when used; several neuralis processes share one
renewal. logout revokes the refresh grant on the host; an access token already
issued stays valid until it expires, at most one hour.
Call a route
neuralis request GET @neuralis/admin/audit -f last=20
neuralis request POST @neuralis/agent-core/conversations -f agentId=<agent-id> -f title=Triage
neuralis request GET @neuralis/brain-core/sources --jq '.[].source'<package>/<route> is the path after /api/packages/; a scoped package takes
two segments. A full URL, a scheme, //, .. or a # fragment is refused
before anything is sent.
| Flag | Meaning |
|---|---|
-f key=value | A string field: a query parameter on GET, a JSON body key otherwise |
-F key=value | A typed field: true, false, null and integers become JSON values; key=@file or key=@- sends the file's (or stdin's) content as a string, so a secret never sits in the command line |
--input file|- | The raw request body (an object body, a binary) |
--form key=value|key=@file | A multipart/form-data body, for file uploads |
--jq expr | Filter a successful JSON answer (jq 1.8 is built in) |
-i | Print the status line and headers first |
--max-time s | The client deadline (inside a skill shell it defaults to the shell's own budget minus ten seconds) |
-f/-F, --input and --form are mutually exclusive. A mutation with none
of them sends no body.
A successful answer (202 and 207 included) prints the body on stdout, byte
for byte, and exits 0. Anything else prints HTTP <code> and the server's own
error body on stderr, leaves stdout empty and exits 1 — so a --jq filter
or a pipe never mistakes an error for data. Exit codes:
| Code | Meaning |
|---|---|
0 | Success |
1 | A non-2xx answer, or another failure |
2 | A usage error — nothing was sent |
3 | No usable credential (not signed in, or the renewal was refused) |
4 | No answer at all (connection, DNS, TLS), or a redirect — a credential is never forwarded |
28 | The client deadline passed; the host may still finish the request |
A mutation is never retried for you: check the state before running it again.
A few operations stay with a person at the workspace, whoever asks — connecting a provider
account or storing a secret, for example. The CLI is an agent-class caller, so those routes
answer 403 human_only; do them in the browser.
Skills
neuralis skill list # the skills this agent may use
neuralis skill read <skill-id> # the SKILL.md text, byte for byteThe list is the same per-caller catalog the workspace uses, so a skill that is hidden from you or switched off for the agent is absent here too.
Tools over MCP
neuralis mcpneuralis mcp is a stdio MCP server for an agent client's MCP configuration: it
forwards every message to the host's MCP endpoint with your MCP grant, so the
host stays the only authority over which tools exist and who may call them. A
request lost to a dropped connection is reported, never replayed. Some clients
keep MCP tools behind a tool search instead of listing them up front.
From a client's plugin marketplace
Claude Code and Codex can install the CLI as a plugin from the
neuralisapp/neuralis marketplace. The plugin carries the bootstrap skill and
the neuralis mcp server, which it starts from your PATH: install the CLI
globally (see Install) and sign in with neuralis login first.
# Claude Code
/plugin marketplace add neuralisapp/neuralis
/plugin install neuralis@neuralisIn Codex, add the marketplace neuralisapp/neuralis from /plugins and install
the neuralis plugin.
Export a plugin
neuralis plugin export --for claude --out ./my-agent-pluginWrites the agent's active skills — byte for byte, with their scripts and
references — as a plugin for claude, codex, cursor or a plain agents
skill tree, with an MCP configuration that starts neuralis mcp. The export is
refused whole rather than cut: past the host's file, byte or entry limits, on a
file that cannot be read in full, or on a source the host cannot list
completely. A file from a source on the operator's host machine can be at most
1 000 000 bytes. An existing target folder is never overwritten. Exported files
stay on that machine after access is withdrawn; every later call is checked
again.
Start Claude Code or Codex with your agent
neuralis launch claude --project <project-id> --agent <agent-id>
neuralis launch codex --project <project-id> --agent <agent-id>
neuralis launch claude --conversation <conversation-id> # that conversation's own toggles
neuralis launch claude --new # a new conversation for this launchlaunch asks the host what this agent may use right now — its skills, its
packages overview and runtime summary (no rule or instruction text, no container
paths) — writes it once as a content-addressed set under ~/.neuralis/launch,
and starts the client with it: the skills as a session plugin (Claude Code), the
summary appended to the system prompt, and the tools through neuralis mcp
under the server id neuralis_launch. An unchanged set is reused without
writing anything; sets no running client or conversation still points at are
removed by the next launch. No token is ever written into a set.
Three layer modes decide how this meets your own client setup:
| Mode | What the client loads |
|---|---|
merged (default) | Your own client configuration plus the agent's skills, tools and context |
governed | Only the capabilities set in Neuralis. Your own client deny rules and hooks are not loaded either — use merged if you rely on them. Claude Code only |
native | Your client exactly as it is, with no Neuralis layer |
Codex has no session-plugin folder: it receives the summary and a pointer to the
agent's skills in its developer instructions, and reads a skill with
neuralis skill read when the task needs it. Codex is not started in
governed mode.
Everything after -- is passed to the client, except the flags that would
replace the layer launch sets up; those are refused by name.