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;
  • call With account or developer operations as those commands become available;
  • 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 should support JSON output. The first available read command is:

Terminal window
sudomimus whoami --json

It returns the current With account identity as JSON. If the access token is near expiry, the CLI refreshes it through Connect before calling With.

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 http://localhost:7701 \
  --connect-api-base-url http://localhost:7101 \
  --with-api-base-url http://localhost:7301

The same values can be supplied with environment variables:

Terminal window
SUDOMIMUS_DEVICE_API_BASE_URL=http://localhost:7701
SUDOMIMUS_CONNECT_API_BASE_URL=http://localhost:7101
SUDOMIMUS_WITH_API_BASE_URL=http://localhost:7301
SUDOMIMUS_WITH_APPLICATION_ANCHOR=sudomimus-with
SUDOMIMUS_CLI_HOME=.sudomimus-cli

Endpoint overrides are useful for agents running inside a repository checkout, because the assistant can point the CLI at a local Serverless process without changing stored production credentials.

Security model

Section titled “Security model”

The CLI never needs the sudomimus-with client-auth private key. Login uses the generic device authorization flow: the CLI asks device-api for a device code, the user completes normal Sudomimus authentication in the browser, and the CLI receives an access/refresh token pair only after approval.

This keeps the high-risk step human-confirmed while still making the post-login surface easy for agents:

  • the browser owns passkeys, email OTP, OAuth, and enterprise federation;
  • the CLI owns token refresh and API calls;
  • the assistant owns command selection and JSON parsing;
  • credentials stay in the local CLI store instead of being copied into prompts.