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.

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

In a source checkout before the CLI is published, run the workspace package directly:

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.