◈ CLI Reference

Command Reference

Every command, flag, and mode in the sudoji CLI.

ℹ

This page covers the Linux @sudoji/cli (npm-installed). The macOS/Windows agent is a separate, smaller binary with a different command set — see Command differences for what it does and doesn't support.

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, grep, know_me, export_server_configapproval: None for read-only tools; export_server_config still prompts (it writes a file)

--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, know_me, export_server_config, propose_commandapproval: Mostly none — propose_command is currently policy-gated like run_command, so it can still prompt [y/N] before showing a proposal

--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, know_me, export_server_config, run_commandapproval: [y/N] per command (or policy auto-allow) — Approve all auto-approves the rest of the turn, Stop cancels an in-flight command

✦

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 whoami[options]

Show which profile is currently logged in and a masked preview of the stored key. Useful for confirming which account a machine is authenticated as before running anything.

FlagDescriptionDefault

--profile <name>Profile to check.default

terminal

sudoji whoami

expected output

  profile  default
  token    sudoji_sk_a1b2c3d4…

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?"

✦

Ask it to search the web for … (or "look this up online", "google it") and it will — this works in sudoji ask, sudoji chat, and portal-forwarded daemon sessions alike, not just the web chat.

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

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

# --interpreter none matters — otherwise pm2 tries to run the file
# through Node itself instead of letting the shebang handle that
pm2 start $(which sudoji) --name sudoji-daemon --interpreter none -- 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.

✦

There's no flag to set a device's display name — it defaults to the API key's name on first connect. Rename it any time by clicking the title on the Devices page; the raw hostname stays visible in that device's Device Context panel.

sudoji context[text] [options]

View, set, or auto-build 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

--buildAuto-discover OS, runtimes, installed services, and running pm2/systemd processes, and save the result as context — no need to write it by hand.—

--clearRemove the saved context.—

auto-discover context (fastest way to get started)

sudoji context --build

set context by hand instead

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

✦

Run sudoji context --build once after installing on a new server — it auto-discovers OS, runtimes, and running services (including pm2 processes) with no typing required. Prefer to write it by hand if you want to add detail the auto-discovery can't see, like which environment (production/staging) or specific constraints.

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.—

--ask <question>Override the default analysis prompt with a specific question about the logs."Analyse these logs and identify any errors, warnings, or anomalies."

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

ask a specific question about the logs

sudoji logs --source pm2 --unit api --ask "did this crash from an out-of-memory error?"

sudoji tool<name> [options]

Run a built-in Sudoji tool directly against this device, without writing out a natural-language request. This is the same underlying mechanism the portal's '+ run tool' chat menu uses — CLI, chat, and portal all funnel into the same tool call.

FlagDescriptionDefault

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

--profile <name>Named credential profile.default

--jsonEmit newline-delimited JSON events instead of plain text.—

profile this device — processes, ports, services, packages, docker, cron, web configs, cloud metadata

sudoji tool knowme

export a rebuild manifest before migrating this server to a new host

sudoji tool exportconfig

ℹ

knowme is read-only and runs without a prompt. exportconfig writes a manifest file to disk on the server — installed packages, pm2/nginx/systemd config, cron, firewall rules, and .env variable names only, never values — so it requires a one-time [y/N] approval since it performs a write, unlike the read-only tools above. Copy the resulting file off the server (e.g. scp) before decommissioning it.

sudoji keys<subcommand>

Placeholder subcommands that point you to the dashboard for API key management — list, create, and revoke each print a link to https://sudoji.io/dashboard/settings and exit. Full key management from the CLI is planned for a future release; for now this isn't scriptable.

list keys (opens the dashboard)

sudoji keys list

create a new key (opens the dashboard)

sudoji keys create

revoke a key by ID (opens the dashboard)

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

know_meSurvey this device (processes, ports, services, packages, docker, cron, web configs) and summarize what it is/does.Auto

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

propose_commandsuggest mode only — proposes a command without running it. Currently policy-gated the same as run_command, so it can still prompt [y/N] before showing the proposal.[y/N]

export_server_configSurvey this server for migration/rebuild and write a manifest to disk. Not read-only (it writes a file), so it requires approval.[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 →