npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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 projects

Open 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 - --json

Sign-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 logout

ONTO_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 - --json

Example 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 --help

For 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 test

Tests 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.