@modem-dev/cli

Agent-friendly command-line access to the Modem public API.

Requirements

• Node.js 24 or newer
• A Modem organization with permission to create API keys

Install

npm install --global @modem-dev/cli

Confirm the installed version:

modem --version

Authenticate

modem auth login

Login opens https://app.modem.dev/org/settings/api-keys?create=cli. Sign in if needed; the existing create-key dialog opens with the name Modem CLI, where you choose an expiry, create the key, and copy it once. Return to the terminal and paste the key into the masked prompt. The CLI verifies it with GET /v1/whoami before replacing any existing credential. Pass --no-open to print that URL instead of opening a browser; it still prompts for the pasted key.

The only credential source is ~/.modem/credentials.json, containing exactly { "api_key": "modem_..." }. The directory is mode 0700 and the file is mode 0600; this CLI does not use an OS keychain.

Interactive login is intentionally unavailable to agents and CI. Automation must securely provision that exact file under HOME, then verify it before work begins:

modem whoami --json

Use the API

Discover the generated resource commands:

modem commands list topics
modem describe topics list

Command paths use noun-first order: modem <resource> <action>. Append --help to an ordinary command path for human-readable usage, such as modem topics --help or modem topics list --help. Agents should use commands and describe for structured discovery rather than positional forms such as modem help topics or modem topics help.

Run resource commands with JSON input:

modem topics list --input '{"search":"billing","priorities":["high"]}'
modem topics update <topic-id> --input '{"priority":"high"}'

Request input from stdin or @file is capped at 16 MiB. File input must name a regular file; links, directories, pipes, devices, and sockets are refused.

Send a lower-level authenticated request when a generated command is not suitable:

modem api GET /topics --query limit=10

Use --json or --format pretty on execution commands when output must be machine-readable. commands list and describe always emit JSON without an output flag. Raw API dry runs are shape-only: stdout contains the method, path/query/header counts, body byte count, a finite json|form|text|other body kind, and body/recovery SHA-256 values. It never echoes caller-supplied request paths, query entries, headers, content types, idempotency keys, or bodies; the exact request stays in mode-0600, digest-bound replay artifacts. Generated replay argv attempts to remove those private artifacts after successful response output and retains unexpired artifacts when the request or output fails. Generated and raw mutations also bind retries to the organization returned by GET /v1/whoami; server-side revision preconditions are deferred, so --plan reports concurrency_protection: "unavailable".

Responses are capped at 16 MiB in memory and --all at 64 MiB across pages, with 30-second header/body-idle deadlines and a five-minute total body deadline. Numeric Retry-After metadata is retained, but executable sleep guidance is emitted only for delays of at most five minutes. Use --output-file <new-path> for raw GET/HEAD exports up to 1 GiB; the CLI streams the response to a reserved mode-0600 file and returns a digest receipt. Run modem --help for the complete command list.

Install the bundled agent skill

The package includes a Modem CLI skill for agents that discover filesystem-installed skills:

modem skill install --scope user --link
modem skill status --json

Use --host claude, --host codex, --host cursor, or --host gemini when targeting a host other than the default .agents directory.

Log out and revoke

modem auth logout

Logout removes the local credential file only. Revoke the server-side key from the dashboard API-keys page the command prints.

Publishing

pnpm run verify:pack   # packs, installs into an empty production consumer, and runs the installed CLI
pnpm run release

The package uses concrete registry versions, so either pnpm or npm can publish it without package-manager-specific protocol rewriting.

Updating the OpenAPI command catalog

The committed openapi/openapi.json file is the CLI's public source of truth. To refresh it, obtain a reviewed public OpenAPI export from the API maintainers, preserve its generated formatting, and inspect every description for private implementation or rollout details before committing it:

# Replace openapi/openapi.json with the reviewed public export, then validate it:
pnpm test