# Use Onto from a terminal or coding agent

The Onto CLI connects to your hosted Onto organization from a terminal, script,
or agent with shell access. It uses the same service and OAuth permissions as
[the native MCP connection](./prompt.md). Choose MCP for a client with native
MCP tools and interactive Story viewers; choose the CLI for shell commands and
JSON output. The CLI does not require configuring an MCP connection in your agent.

## Install

Requires **Node.js 24 or newer** and **macOS or Linux**. Windows is not supported
by this release. Check `node --version`, then install the public package:

```sh
npm install -g @ontoapp/cli
onto --version
```

No repository checkout, pnpm, Studio build, or npm account is needed. For a one-off
command, use `npx @ontoapp/cli@0.1.1 --help`. Scripts and agents that need a fixed
version can install `@ontoapp/cli@0.1.1`. To update a global install, run
`npm install -g @ontoapp/cli@latest`.

## Sign in and verify the organization

For production:

```sh
onto --endpoint https://app.onto.space/api/mcp login
onto --endpoint https://app.onto.space/api/mcp status --json
onto --endpoint https://app.onto.space/api/mcp projects --json
```

If you received this guide through a setup prompt, use `/api/mcp` on the **same
origin as the guide URL** for every command. Keep its scheme, hostname, and port;
replace `/agent-setup/cli.md` with `/api/mcp`. In particular, a staging setup prompt
uses `https://staging.app.onto.space/api/mcp`, not the production example above.
Quote the endpoint safely when inserting it into a shell command. Do not put
organization IDs, tokens, query strings, or fragments in the endpoint.

Login prints an authorization URL. Open that URL in your preferred browser,
sign in, choose the organization you want to use, and approve access. Login does
not launch a browser automatically. The browser must reach the CLI's callback at
`http://127.0.0.1:43123/oauth/callback` on the machine running the command. A remote
terminal requires an explicitly configured loopback tunnel; if the callback port
is occupied, finish the other login or free that port before retrying.

`status --json` returns the verified organization and the server's current agent
guide. Every connected command also reports the verified organization to stderr.
Check this organization before doing work. If it differs from the user's intended
organization, stop and repeat login for the correct organization. Do not infer the
organization from browser tabs or change the account silently. A successful
project listing with no projects is a valid connection.

Credentials are separate for each endpoint and profile. Use `--profile NAME` on
**every** command when working with a separate account. `ONTO_ENDPOINT` and
`ONTO_PROFILE` supply defaults, but explicit flags take precedence. `onto logout`
removes the chosen endpoint/profile's local credentials; it does not revoke the
server-side OAuth grant.

For application-scoped automation, CLI 0.1.1 also accepts an existing runtime-agent
credential through `ONTO_RUNTIME_TOKEN`, `ONTO_APPLICATION_ID`, and
`ONTO_RUNTIME_ENDPOINT`. Set all three through the process environment or a secret
manager, then run `onto status` to verify the application. This mode uses the
application's existing authority, not organization OAuth. An explicit endpoint must
match the credential's endpoint. See the [CLI reference](https://www.npmjs.com/package/@ontoapp/cli)
for runtime authentication; never put a token in a command-line argument.

## Instructions for an agent

When asked to set up the CLI:

1. Confirm this environment has shell access, macOS or Linux, and Node.js 24+.
   If a prerequisite is missing, explain the required step. Do not replace the
   user's Node installation or run privileged installation commands implicitly.
2. Install `@ontoapp/cli` from npm, or reuse a working installation. Do not clone
   the application repository, install an MCP wrapper, or edit global agent
   instructions, `AGENTS.md`, or `CLAUDE.md`.
3. Derive the endpoint from this guide's URL as described above. Keep it explicit
   in all setup and verification commands so an environment variable cannot send
   setup to a different deployment.
4. Run `onto --endpoint '<MCP_URL>' login`. Show the authorization URL to the user
   and keep the command running for its callback. Let the user complete normal
   sign-in and organization consent. Do not handle passwords, copy tokens, or
   inspect browser sessions. Login allows five minutes.
5. Run `onto --endpoint '<MCP_URL>' status --json`. Follow the returned operating
   guide and report **Connected to [organization name]** using the verified result.
   Confirm it matches any organization the user requested.
6. Run `onto --endpoint '<MCP_URL>' tools onto_list_projects --json`, then
   `onto --endpoint '<MCP_URL>' projects --json`. Report the available projects.
   Do not claim setup succeeded until verification succeeds. Do not change project
   data as part of setup.

Replace `<MCP_URL>` with the derived URL; it is a placeholder, not a literal URL.
For later work, keep the same explicit endpoint and profile on every command.

## Discover operations and run commands

Use the server's live schemas rather than guessing operation names or arguments:

```sh
onto search 'read model' --limit 5 --json
onto tools onto_read_model --json
onto call onto_read_model --args '{"project":"my-project"}' --json
```

These abbreviated examples use the default production endpoint and default
profile. Add your verified `--endpoint` and `--profile` flags when they differ.
Replace `my-project` with an identifier returned by your project listing.

`tools` lists the advertised MCP tools. `tools NAME` also resolves exact names
of operations available through Code Mode. Check `schemaStatus` and any returned
guidance before invoking an operation whose schema is incomplete. `call` handles
Code Mode automatically; it routes operations omitted from the small MCP tool
catalog through hosted execution.

For several operations, write an async function to a file and send it to Onto:

```js
// list-projects.js
async () => {
  return await onto.call('onto_list_projects', {});
}
```

```sh
onto exec list-projects.js --json
```

The source executes on Onto, not on the local computer. Await every operation.
Hosted execution allows 30 seconds, 64 operation calls, four concurrent calls,
64 KiB of source, and 64 KiB of returned JSON. Return a small summary when a full
result would exceed the limit. The CLI's `--timeout` cannot extend server limits.

## Results and safe retries

`--json` writes the complete MCP result to stdout; diagnostics go to stderr. Check
both the process exit code and `isError`. Code Mode results contain the operation
output in `structuredContent.result` and include an `operationCount`. Some tools
provide JSON in text content instead, so preserve the full envelope when parsing.

Exit codes are 0 for success, 1 for tool/network errors, 2 for invalid local
arguments, 3 for sign-in/access failures, 4 for a missing tool or capability, and
130 for interruption. For expired authorization, log in again. For access denied,
report the error and check the intended organization and permissions.

After verification, the CLI does not automatically reauthorize or resend a
command. A timeout, cancellation, or broken connection does not prove a write was
cancelled. Read current state before retrying, and preserve revision, generation,
request, or runtime operation IDs as instructed by the server. Follow its
read → preview → apply authoring workflow, within the user's requested scope.

Story viewers return text in the terminal. Browser-local records and Fact Log
operations require an explicitly selected open Studio session; the CLI does not
choose one. Calls to `onto_show_fact_log` and `onto_read_browser_fact_log` wait for
the completed page using the original request ID. Keep Studio open; failed or
timed-out reads exit with an error. Other asynchronous browser operations still
require explicit result polling. Published application data is separate from
browser-local test data.

Use `onto --help` for the command list and the
[npm README](https://www.npmjs.com/package/@ontoapp/cli) for the full CLI reference.
