---
title: Sudomimus CLI for AI agents
description: Use the Sudomimus CLI as a shell-friendly control surface for AI
  coding assistants, local automation, and account checks.
editUrl: true
head: []
template: doc
sidebar:
  order: 4
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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](/en-us/native/overview/) instead.

## First login

Installed CLI examples use the `sudomimus` binary:

```bash
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:

```bash
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

Commands that expose data to agents should support JSON output. The first available read command is:

```bash
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:

```text
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

For local development, the CLI accepts explicit endpoint overrides:

```bash
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:

```bash
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

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.