@ontoapp/cli
v0.1.1
Published
Onto CLI for terminals, scripts, and coding agents
Readme
Onto CLI
A terminal client for Onto. Use it from a terminal, a shell-capable agent, or a script. Requires Node.js 24+ on macOS or Linux.
Install and connect
npm install -g @ontoapp/cli
onto login
onto status
onto projectsOpen the URL printed by onto login in your browser, sign in to Onto, and select
the intended organization. onto status confirms that organization before you
start working. No repository checkout or local Studio installation is required.
To run without a global installation, use npx --package=@ontoapp/cli onto login
and the same prefix for later commands, for example
npx --package=@ontoapp/cli onto projects. You can pin a version in the package
specifier, such as @ontoapp/[email protected].
Give your agent the CLI setup guide for installation, sign-in, organization verification, operation discovery, and safe execution instructions.
CLI or MCP?
| Connection | Use it for | Setup | | --- | --- | --- | | CLI | Terminals, shell-capable agents, and scripts | CLI setup guide | | MCP | Native agent tools and interactive Story/Fact Log viewers in supported clients | MCP setup guide |
Both connect to the same hosted Onto service and follow the same Onto permissions.
User connections use browser OAuth to select an organization; application-scoped
runtime credentials are also supported. The MCP endpoint is
https://app.onto.space/api/mcp. The CLI uses that MCP service underneath,
including hosted Code Mode, and prints viewer results as text. Choose either
connection in Settings → Connected agents.
Commands
onto stories my-project
onto tools
onto tools onto_read_model
onto search onto_read_model
onto call onto_read_model --args '{"project":"my-project"}' --json
onto call onto_read_model --file request.json --json
printf '{"project":"my-project"}' | onto call onto_read_model --file - --jsonSign-in and profiles
Login prints an OAuth authorization URL. Open it in your preferred browser, sign in,
and select the organization. The CLI listens on 127.0.0.1:43123 for the
callback and verifies the organization by calling onto_start_session. It never
launches an operating-system browser. --no-browser explicitly documents this default.
That fixed callback exactly matches the public client metadata document used by
Clerk. If the port is busy, finish the other login or free the port and retry;
the CLI does not silently choose an unregistered callback port.
When used on a remote terminal, the browser must be able to reach that terminal's
loopback callback (for example through a port tunnel); there is no pasted-token flow.
The official MCP SDK uses a Client ID Metadata Document (CIMD) when the issuer
advertises support. Production uses
https://app.onto.space/oauth/onto-cli.json; staging uses
https://staging.app.onto.space/oauth/onto-cli-staging.json. These public documents
identify the CLI and its allowed callback; they contain no credentials. Before
printing the sign-in URL, the CLI checks that the selected document is reachable
and matches its client ID and callback. A deployment without the document reports
a setup error. Issuers that only advertise dynamic registration still use the
SDK's existing registration flow.
Each command reports the server-verified organization to stderr. It never chooses an organization from a browser tab. Use a separate profile for another account, or log in again to change the organization:
onto --endpoint https://staging.app.onto.space/api/mcp --profile work login
onto --endpoint https://staging.app.onto.space/api/mcp --profile work status --json
onto --endpoint https://staging.app.onto.space/api/mcp --profile work logoutONTO_ENDPOINT and ONTO_PROFILE provide defaults; explicit flags take precedence.
Credentials are isolated by the exact endpoint and profile in $XDG_CONFIG_HOME/onto
(when absolute), otherwise ~/.config/onto. The directory is user-owned with mode
0700, credential files are mode 0600, and updates use atomic replacement. Tokens are
stored on disk, not encrypted; protect your OS account and backups accordingly.
There is no access-token command-line option. logout removes only the selected
local credentials; it does not revoke the OAuth grant at Clerk.
Application-scoped runtime credentials
For an existing runtime-agent credential, supply these three environment variables through your secret manager or process environment:
ONTO_RUNTIME_TOKEN: the runtime-agent token issued for the application.ONTO_APPLICATION_ID: the application ID returned when the credential was issued.ONTO_RUNTIME_ENDPOINT: the exact MCP endpoint that issued it.
Then run onto status to verify the application. Runtime mode never uses or writes
OAuth credentials. It reports the verified application rather than an organization;
its tools and permissions are the same as a runtime-token MCP connection. Use
onto tools and onto call NAME to discover and invoke those tools. Code Mode and
organization-authoring tools are available only when the server advertises them.
The runtime endpoint supplies the default endpoint in this mode. An explicit
--endpoint or ONTO_ENDPOINT must match it exactly; a mismatch fails before any
request. All three runtime variables are required together. The token is never
accepted as a command-line flag or saved to the CLI credential store. Runtime
mode has no login, logout, or --profile: unset the three variables to return
to OAuth. Revoke runtime credentials through the application's existing controls.
Discover operations and run Code Mode
Code Mode is detected from the server's advertised tools. projects and named
call operations automatically use hosted execution when Code Mode is enabled.
Session checks, viewers, search and execution tools are called directly. Endpoints
without Code Mode continue to use their named tools. You can also search for
operation schemas or send an async function explicitly:
onto search 'projects' --limit 5 --json
onto tools onto_list_projects --json
onto exec list-projects.js --json
cat list-projects.js | onto exec - --jsonExample list-projects.js:
async () => {
return await onto.call('onto_list_projects', {});
}exec sends the file verbatim to hosted onto_execute; it never evaluates local
JavaScript. If onto_execute or onto_search is absent, the command reports that
Code Mode is unavailable. Named call remains available through hosted execution
for operations omitted from the smaller Code Mode tool catalog. The CLI does not maintain
its own catalog, operation schema validator, authorization rules, or backend.
Search queries are trimmed and must contain 1–200 characters; --limit accepts
1–10. Exec source is limited to 64 KiB of UTF-8, including whitespace. These
inputs are checked before sign-in or network access. Hosted execution has a
30-second deadline, at most 64 operation calls, four concurrent calls, and 64 KiB
of returned JSON. --timeout controls the client deadline and cannot extend
those server limits. Return a small summary from scripts when the full operation
result would exceed the result limit. Every operation must be awaited.
Output and errors
--json writes the complete MCP result as one JSON line to stdout, including
content, structuredContent, and isError. Tool errors also produce JSON and
exit 1. Automatically routed calls return the Code Mode execution result, with the
operation's data in structuredContent.result and an operationCount. Progress
and errors go to stderr. Without --json, calls print the server's
text content. Story viewers use that text fallback; the terminal does not render an
MCP App. tools follows all discovery pages and lists the advertised MCP tools.
tools NAME first checks those tools, then uses exact-name Code Mode search for
operations hidden from that list. The returned operation includes its published
input schema, invocation guidance, and schemaStatus; if the server cannot publish
a schema, its status and guidance are preserved. Use search for keyword discovery.
Exit codes: 0 success, 1 tool/network failure, 2 invalid local arguments, 3 sign-in
or access failure, 4 missing advertised capability, 130 interruption. --timeout
sets the complete MCP handshake deadline and each later request timeout in
milliseconds (default 60000). Fact Log polling also uses this deadline, capped at
two minutes after the initial request. Login allows five
minutes. SIGINT/SIGTERM cancel pending work and close the callback listener.
Working with Onto data
The CLI may refresh authorization during initialization and the read-only session check. After verification it never automatically reauthorizes or resends a command. Cancellation, timeout, or a broken connection do not prove a write was cancelled. Inspect current state before retrying. Preserve authoring revision/generation and request IDs, and runtime operation IDs, as instructed by the service. The CLI does not invent these values. Follow the read → preview → apply authoring workflow.
Browser-local records and Fact Log requests need an explicitly selected open Studio
session. Discover sessions and pass the chosen session ID through named tool calls;
the CLI does not select one. Calls to onto_show_fact_log and
onto_read_browser_fact_log wait for the page using the same bounded reader as
the MCP viewer. They poll only the original request ID and report completion or
a read failure; --json retains the completed receipt and MCP envelope. Keep
Studio open. Other asynchronous browser requests still require explicit result
polling. Published runtime data
is separate from browser-local test records.
Maintainer development
From a source checkout, install the CLI's own dependencies and run it directly:
cd cli
pnpm install --frozen-lockfile
node bin/onto.mjs --helpFor a local onto command, use npm link from this directory after installing.
The package has its own dependencies and lockfile; no Studio installation or build
is required. Its Fact Log protocol/reader is also imported by the MCP viewer and
server schemas. After editing it from the repository root, run
node scripts/build-cli-fact-log-types.mjs and pnpm build:mcp-ui; test:mcp checks
that the generated declarations and viewer match their source.
pnpm check
pnpm testTests use local mock OAuth/MCP servers with the official SDK transport, including
an issuer that advertises CIMD without a dynamic registration endpoint. The Studio
deployment serves the two documents from studio/public/oauth/; its routing tests
verify that Clerk can fetch them without a browser handshake. These assets must be
deployed before the corresponding hosted login can work. Tests do not authenticate
against a hosted account or mutate real projects. Maintainers with repository
access can find the implementation scope and acceptance record in
docs/features/cli/spec.md.
