Skip to content
Sudomimus

Sudomimus CLI for AI agents

View as Markdown

The Sudomimus CLI is the best control surface when an AI assistant needs to operate Sudomimus directly. It gives the assistant normal shell commands instead of a browser session, while keeping authentication in the user’s browser through the device authorization flow.

Use it when the assistant needs to:

  • confirm which Sudomimus account is active;
  • refresh an expired CLI session without asking the user to sign in again;
  • discover organizations and inspect their resource usage;
  • list applications, inspect application configuration, and check signing-key lifecycle state;
  • work in an editor, terminal, or CI-like agent environment where browser cookies are not available.

The CLI is for operating Sudomimus itself. If you are building your own CLI application that authenticates your users, choose the Native integration path instead.

Prerequisites and source checkout

Section titled “Prerequisites and source checkout”

Use Node.js 26 or newer. For a source checkout, first complete the repository’s setup instructions and install its workspace dependencies with the repository’s configured pnpm version. Run the following commands from the repository root:

Terminal window
make dev-cli ARGS="--help"
make dev-cli ARGS="login --no-open"

The source entry builds the CLI before running it. Pass other command arguments through ARGS in the same way. The examples below use an already-installed sudomimus binary; they do not establish a package publication or installation baseline.

First login

Section titled “First login”

Installed CLI examples use the sudomimus binary:

Terminal window
sudomimus login

The CLI prints a verification URL and user code, opens the browser when possible, and waits for the device grant to complete. For a remote agent or terminal-only environment, keep the browser step manual:

Terminal window
sudomimus login --no-open

The local session is stored under $SUDOMIMUS_CLI_HOME/credentials.json when that environment variable is set, otherwise under ~/.sudomimus/credentials.json. The file contains bearer credentials; an assistant should use the CLI, not read or print this file.

Machine-readable output

Section titled “Machine-readable output”

Commands that expose data to agents support JSON output:

Terminal window
sudomimus whoami --json
sudomimus org list --json
sudomimus org show <organization-anchor> --json
sudomimus app list <organization-anchor> --json
sudomimus app show <application-anchor> --json
sudomimus app keys <application-anchor> --json

List commands are cursor-paginated. Pass the returned opaque cursor unchanged when another page is available:

Terminal window
sudomimus org list --cursor <cursor> --json
sudomimus app list <organization-anchor> --cursor <cursor> --json

If the access token is near expiry, the CLI refreshes it through Session API before calling With. Developer commands are read-only and use the same organization membership and role checks as the With portal.

For prompts, tell the assistant to prefer CLI JSON output over scraping terminal prose:

Use the Sudomimus CLI for Sudomimus account operations. If a command supports
--json, use it. If the CLI is not logged in, ask me to run `sudomimus login
--no-open` and paste the verification URL/code into my browser. Do not read or
print ~/.sudomimus/credentials.json.

Endpoint overrides

Section titled “Endpoint overrides”

For local development, the CLI accepts explicit endpoint overrides:

Terminal window
sudomimus login \
  --device-api-base-url https://sudomimus-device-api.your-domain.com \
  --session-api-base-url https://sudomimus-session-api.your-domain.com \
  --with-api-base-url https://sudomimus-with-api.your-domain.com

The same values can be supplied with environment variables:

Terminal window
SUDOMIMUS_DEVICE_API_BASE_URL=https://sudomimus-device-api.your-domain.com
SUDOMIMUS_SESSION_API_BASE_URL=https://sudomimus-session-api.your-domain.com
SUDOMIMUS_WITH_API_BASE_URL=https://sudomimus-with-api.your-domain.com
SUDOMIMUS_WITH_APPLICATION_ANCHOR=sudomimus-with
SUDOMIMUS_CLI_HOME=.sudomimus-cli

Endpoint overrides are useful for agents running on self hosted, or enterprise internal hosted sudomimus instance, because the assistant can point the CLI at any instance without changing stored production credentials.

login stores the endpoints that own the credential profile. On whoami, org, and app read commands, --session-api-base-url and --with-api-base-url apply only to that command. Even when the command refreshes and stores a rotated token pair, it keeps the login-time endpoints for the next command.

Unattended work

Section titled “Unattended work”

CLI sign-in still requires a user to approve the device code. Do not copy the CLI’s saved personal session to a server or pipeline for long-term use.

For a job that must run unattended, give it separate programmatic access. Create an agent or automation that matches the way it works, then issue a dedicated credential.