◈ CLI Reference

Command Reference

Every command, flag, and mode in the sudoji CLI — v0.1.20 and later.

Commands

Agent modes

Every sudoji ask and sudoji do call runs in one of three modes, controlled by --mode. The mode determines what tools the AI can call and whether any commands are executed on your server.

--mode diagnoseDEFAULT

Read-only analysis. The agent reads files and logs, identifies the root cause, and explains what went wrong. No commands are proposed or executed.

tools: read_file, list_dir, grepapproval: None required

--mode suggestREAD + PROPOSE

Diagnoses the problem and then lists the exact commands you should run — without executing them. Safe for cautious environments.

tools: read_file, list_dir, grep, propose_commandapproval: None required (commands are suggested only)

--mode fixEXECUTE

Full agent loop. The agent reads files, proposes commands, and executes approved ones on your server. Each run_command call requires your [y/N] approval unless pre-allowed in settings.

tools: read_file, list_dir, grep, run_commandapproval: [y/N] per command (or policy auto-allow)

✦

Start with diagnose to understand the problem, then switch to fix once you know what needs to change. The agent in fix mode will still diagnose first before touching anything.

Commands

sudoji login[options]

Authenticate the CLI with a Sudoji API key. The key is stored in your OS keychain (macOS Keychain, GNOME Keyring) or in an encrypted file at ~/.sudoji/credentials on headless servers.

FlagDescriptionDefault

--paste <key>Pass the API key directly instead of being prompted. Safe for CI / scripting.—

--profile <name>Store the key under a named profile for multi-server setups.default

interactive

sudoji login

scripted / CI

sudoji login --paste sudoji_sk_your_key_here

# Force file-based storage (no keychain)
SUDOJI_NO_KEYCHAIN=1 sudoji login

sudoji logout[options]

Remove stored credentials for a profile.

FlagDescriptionDefault

--profile <name>Profile to log out.default

terminal

sudoji logout
sudoji logout --profile staging

sudoji doctor

Run a self-check: verifies API key is stored, loads settings, confirms agent.sudoji.io is reachable, and tests that secret redaction is active. Run this after install or after any credential change.

terminal

sudoji doctor

expected output

  ✓  API key stored          sudoji_sk_a1b2c3…
  ✓  Settings loaded         apiBaseUrl: https://agent.sudoji.io
  ✓  API reachable           https://agent.sudoji.io/healthz → HTTP 200
  ✓  Redaction active        "password=super$ecret…" → "password=[REDACTED]…"

All checks passed.

sudoji askMAIN COMMAND<question> [options]

Ask the agent a question about your server. The agent automatically gathers context (OS, Node version, git status, recent logs) and streams the answer to your terminal. The default mode is diagnose — read-only analysis with no command execution.

FlagDescriptionDefault

--mode <mode>diagnose | suggest | fixdiagnose

--no-contextSkip automatic context gathering. Faster for quick questions.—

--max-steps <n>Max agent loop iterations (tool calls).20

--server <url>Override the agent API base URL.—

--profile <name>Use a named credential profile.default

--jsonEmit newline-delimited JSON events — useful for scripting and piping.—

diagnose (default)

sudoji ask "why is nginx returning 502 after my last deploy?"

suggest mode — lists fix commands without running them

sudoji ask --mode suggest "how do I free up disk space on this server?"

fix mode — reads files and runs approved commands

sudoji ask --mode fix "restart nginx and verify it comes back healthy"

skip context for a quick question

sudoji ask --no-context "what does exit code 137 mean?"

sudoji doFIX ALIAS<instruction> [options]

Shorthand for sudoji ask --mode fix. The agent reads your server state and executes approved commands to complete the task. Each run_command call shows the exact command and prompts [y/N] before running.

FlagDescriptionDefault

--no-contextSkip context gathering.—

--max-steps <n>Max tool call iterations.20

--server <url>Override agent API URL.—

--profile <name>Named credential profile.default

--jsonJSON event output.—

update system packages with approval prompts

sudoji do "update all system packages"

check and clean disk space

sudoji do "check disk space and find the top 5 largest directories"

restart and verify a service

sudoji do "restart nginx and confirm it is serving traffic"

investigate and fix a crashing process

sudoji do "find out why pm2 api is crashing and fix it"

sudoji chatENGINEER+[options]

Start a persistent, multi-turn conversation with the agent directly in your terminal. Unlike sudoji ask (which is one-shot), chat keeps full conversation history across turns — the agent remembers what it read and what it found earlier in the same session. Every session is automatically assigned a generated name (e.g. 'Brave Falcon') and saved as a thread in your Sudoji portal. You can rename threads from the portal by clicking the title.

FlagDescriptionDefault

--mode <mode>diagnose | suggest | fix — sets the agent mode. diagnose is read-only (plan/analyse), fix can execute commands with approval.diagnose

--resume <threadId>Resume a previous conversation thread by ID.—

--title <title>Override the auto-generated session name.—

--server <url>Override the agent API base URL.—

--profile <name>Named credential profile.default

plan a change before executing (diagnose mode — safe, read-only)

sudoji chat

  sudoji › I want to add swap space to this server, plan it out for me
  [agent analyses memory, suggests steps…]

  sudoji › how much swap do you recommend given 2 GB RAM?
  › For a 2 GB server I'd recommend 2 GB swap. Here's what I'd run…

  sudoji › exit

execute changes with approval (fix mode)

sudoji chat --mode fix

  sudoji › add 2 GB of swap
  allow? run  fallocate -l 2G /swapfile  [y/N]  y
  ✓ Done.

ℹ

Each sudoji chat session creates a conversation thread visible in your portal under Sessions → Chat tab. If the daemon is running on your server, you can also continue the conversation from the portal web UI — messages you send from the browser are forwarded to the agent on the server in real time.

sudoji daemonENGINEER+[options]

Start the always-on daemon — a persistent WebSocket connection between your server and the Sudoji cloud hub. While the daemon is running, messages sent from the web portal are forwarded to the agent on your server and streamed back to the portal in real time. The daemon also keeps the server listed as online in the portal.

FlagDescriptionDefault

--name <label>Label shown in the portal for this server. Defaults to the machine hostname.—

--server <url>Override the hub WebSocket URL.—

--profile <name>Named credential profile.default

run in foreground

sudoji daemon

run under pm2 (recommended — no second SSH session needed)

# Install pm2 if not already installed
sudo npm install -g pm2

pm2 start "sudoji daemon" --name sudoji-daemon
pm2 save

# Register pm2 as a system service (run the printed command)
pm2 startup

run under systemd

# /etc/systemd/system/sudoji-daemon.service
[Unit]
Description=Sudoji Daemon
After=network.target

[Service]
ExecStart=/usr/bin/sudoji daemon
Restart=always
RestartSec=5
User=ubuntu
Environment=SUDOJI_NO_KEYCHAIN=1

[Install]
WantedBy=multi-user.target

⚠

The daemon requires an Engineer or Enterprise plan. If credits drop to zero, in-progress agent turns are still completed but the daemon will display a low-balance warning and new portal messages will be blocked until you top up.

sudoji context[text] [options]

View or set persistent server context. Whatever you set here is included in the system prompt of every sudoji ask and sudoji do request, so the agent always knows what kind of server it is talking to without you having to repeat it each time.

FlagDescriptionDefault

--clearRemove the saved context.—

set context (runs once per server)

sudoji context "Ubuntu 22.04 LTS. nginx 1.24 + Node 20 + PM2. Production web server for api.example.com. No Docker."

view current context

sudoji context

clear it

sudoji context --clear

✦

Set context once after installing on a new server. The more detail you include — OS version, services running, whether it's production/staging, any constraints — the more targeted the agent's responses will be without you having to repeat that background every time.

sudoji logs[options]

Fetch recent log output from systemd, pm2, or a file, redact secrets, and send it to the agent for analysis. Equivalent to manually copying logs into sudoji ask but faster.

FlagDescriptionDefault

--source <src>systemd | pm2 | filesystemd

--unit <name>Service name (systemd unit or pm2 app name).—

--file <path>Path to a log file (when --source file).—

--tail <n>Number of lines from the end of the log.100

--since <time>Time expression: "2 hours ago", "yesterday", ISO timestamp.—

systemd service

sudoji logs --source systemd --unit nginx
sudoji logs --source systemd --unit postgres --since "2 hours ago"

pm2 app

sudoji logs --source pm2 --unit api --tail 200

log file

sudoji logs --source file --file /var/log/app/error.log --tail 50

sudoji keys<subcommand>

Manage API keys from the CLI. Useful for rotation scripts and automation.

list keys associated with your account

sudoji keys list

revoke a key by ID

sudoji keys revoke <key-id>

Tool execution loop

In fix mode (sudoji do), the agent runs a multi-round loop. Each round the AI decides which tool to call next, the CLI executes it locally, and the result is sent back to continue reasoning.

ToolWhat it doesApproval

read_fileRead the contents of a file on your server.Auto

list_dirList the contents of a directory.Auto

grepSearch for a pattern across files.Auto

run_commandRun a bash command. Shows the command and asks [y/N] before executing.[y/N]

In the terminal, an approval prompt looks like this:

terminal — approval prompt example

  🦚 sudoji  ────────────────────────────────────────

  I'll check disk usage first, then identify the largest directories.

  ▶ run  df -h
  allow? [y/N]  y
  ✓
  │ Filesystem      Size  Used Avail Use% Mounted on
  │ /dev/sda1        50G   43G  7.0G  86% /

  ▶ run  du -sh /* 2>/dev/null | sort -rh | head -5
  allow? [y/N]  y
  ✓
  │ 18G  /var
  │ 12G  /usr
  │  8G  /home
  ...

  ──────────────────────────────────────────────────

Conversation threads

sudoji chat and the daemon both operate on conversation threads — persistent records of a multi-turn agent session. Each thread stores the full message history, which tools were called, and the total token cost. Threads are tied to a server and visible in your portal.

Terminalsudoji chat opens a thread and appends every turn. You can exit and pick up in the portal.

PortalEngineer+ users can send messages from the web UI. The daemon on the server handles the request and streams the response back via Realtime.

DaemonRoutes portal messages to the local agent. Writes assistant responses back to the thread so both sides see the same history.

✦

Thread history is unlimited for Engineer and Enterprise plans. Free plan threads are closed after 7 days of inactivity.

Permission policy

You can pre-approve or pre-deny specific commands so you don't get prompted every time. Policy rules live in ~/.sudoji/settings.json and use a Tool(matcher) syntax.

~/.sudoji/settings.json

{
  "permissions": {
    "allow": [
      "Bash(df:*)",
      "Bash(du:*)",
      "Bash(systemctl status:*)",
      "Bash(journalctl:*)",
      "Bash(npm install:*)"
    ],
    "ask": [
      "Bash(apt:*)",
      "Bash(systemctl restart:*)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(dd:*)"
    ]
  }
}

allowRun without prompting. Use for safe read operations you trust.

askAlways prompt even if the default would allow. Explicit confirmation required.

denyNever run, even if the user tries to approve it. Org-managed deny rules cannot be overridden.

⚠

The policy engine runs entirely on your machine. The cloud never sees your allow/deny lists and cannot override them. Deny rules set by an org-managed policy (/etc/sudoji/managed.json) cannot be removed by user-level config.

Environment variables

SUDOJI_NO_KEYCHAIN

Set to 1 to force file-based credential storage, bypassing the OS keychain. Always set on headless servers without a D-Bus session.

SUDOJI_LAST_STDERR

Set by shell integration. Passes the last command's stderr to the agent as additional context.

SUDOJI_LAST_EXIT

Set by shell integration. Passes the last command's exit code.

SUDOJI_HOME

Override the base directory for credentials and audit log. Defaults to ~/.sudoji.

ANTHROPIC_API_KEY

Required on the agent service. The Claude API key for the reasoning backend.

← Installing the Agent Use cases & examples →