Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

10.3 KB
Raw Blame

title: "CLI Reference" slug: cli-reference summary: "Find the supported command-line surfaces, authentication options, common flags, and the generated command catalog." section: "Reference" section_order: 7 order: 1 diataxis: reference status: active owner: maintainers last_reviewed: 2026-07-21 phase: "-" audience: end-user tags: [cli, terminal, api, automation, reference] related: [cli-connections, control-api-reference, app-command-reference, configuration-reference]

The Dodaios command-line interface (CLI) lets you inspect and control a running Dodaios instance from a terminal. It is a thin client: the command sends a request, while Dodaios performs the action and applies its normal validation and safety rules.

Start with a curated command such as dodaios system status. Use the dynamic dodaios api layer when an operation has no shorter curated command.

Before You Start

  • Install Dodaios so the dodaios, dodaiosctl, and jctl commands are available. The earlier names jarvis and jarvisctl still work as aliases.
  • Start the desktop app or headless server for any command that reads or changes Dodaios. Curated help, version, and schema-cache maintenance work without a running server.
  • For a remote instance, use a trusted private connection and authenticate with its control key. Do not expose the control address directly to the public internet.

Commands affect the computer that runs the Dodaios server, which may be different from the computer where you type the command.

Choose the Right Surface

Surface Use it when What it controls
Dodaios CLI You want to inspect, automate, or manage Dodaios from a terminal A running Dodaios instance
CLI Connections You want Dodaios to use another terminal program External programs installed on the Dodaios host
Control API You are building an HTTP integration The REST operations behind the CLI and app
App Commands You need a stable Dodaios action shared by voice, chat, desktop, CLI, and REST The canonical cross-surface command catalog

The similar names describe opposite directions: the Dodaios CLI lets you control Dodaios; a CLI Connection lets Dodaios control an external CLI.

Choose a Command Layer

Layer Shape Current behavior
Curated commands dodaios <group> <command> Short, human-oriented names for common operations
Dynamic API commands dodaios api <tag> <operation> Built from the target server's OpenAPI description for mounted GET, POST, PUT, PATCH, and DELETE operations
Launcher commands bare dodaios, dodaios serve, and launcher flags Starts or diagnoses the app rather than calling the control CLI

dodaiosctl and jctl are control-only aliases. They are especially useful for top-level help because dodaios --help intentionally shows launcher help, while dodaiosctl --help lists the curated control groups.

The dynamic layer uses the target server's OpenAPI schema. It reuses a local schema cache for up to 24 hours. After that, an api invocation tries to fetch a new schema and falls back to the older cache if the server is unreachable. Run dodaios refresh to clear the cache before the next dodaios api call.

Use the generated Dodaios CLI command catalog for the maintained list of curated groups, arguments, and options. It intentionally does not copy the server-specific dynamic API operations.

Authentication and Target Selection

The CLI resolves the server address and control key separately. Higher rows take priority over lower rows.

Priority Source Best use
1 Global --url or --key A one-call override
2 JARVISCTL_BASE_URL or JARVISCTL_CONTROL_KEY Managed automation with a secret store
3 Profile saved by dodaios auth login Repeated access to one target
4 Live local-instance discovery and the local control key Normal same-computer use
5 http://127.0.0.1:47821 and no key if none can be resolved Local fallback

For remote access, run dodaios auth login --url <server-url> and enter the key in the hidden prompt. The CLI verifies it before saving it. For managed automation, dodaios auth login --url <server-url> --key - reads the login key from standard input. The root-level --key option does not read from standard input. Avoid an inline key because shell history and process inspection can expose it.

The saved profile is a per-user CLI configuration file, not the provider-key vault. POSIX systems restrict its file permissions; Windows relies on the user profile's access controls. Use dodaios auth logout on a shared or retired computer.

Common Options

Only the root options --json, --url, and --key go before the command group. Command options go after the command and are available only when that command's help lists them.

Option Scope Meaning
--json Root Force machine-readable JSON output
--url Root Override the target server for this call
--key Root Override control authentication for this call; avoid inline values
--dry-run Command Preview the request without sending it when the command exposes this option
--yes, -y Command Authorize an operation classified as dangerous
--json-body - Dynamic API command Read a JSON request body from standard input
--request-timeout Dynamic API command Override that operation's HTTP read timeout
--persist / --no-persist Supported curated setting command Choose whether a change survives restart

Interactive terminals receive readable tables where possible. Piped output defaults to JSON even without --json, but scripts should pass --json explicitly so their intent stays clear.

Read-only requests and reversible changes can run immediately. Dangerous operations fail unless you add --yes or explicitly set JARVIS_CLI_ASSUME_YES=1; the CLI does not open an interactive confirmation prompt for them. Review --dry-run output first when the command supports it. The preview can include the request body, so do not share it when the body contains private information.

Discover Commands and Help

  • Run dodaiosctl --help for every curated top-level group.
  • Run dodaios <group> --help and dodaios <group> <command> --help for exact arguments and options.
  • Run dodaios api --help to fetch or reuse the dynamic API tree, then continue with a tag and operation.
  • Run dodaiosctl --install-completion to install completion for the current shell. Completion uses only the cached API schema and does not make a network request.
  • Browse App Commands with dodaios commands list and inspect one definition with dodaios commands show <command-id>. These commands describe the shared app catalog; they do not execute every entry themselves.

Platform and Host Limits

The control client runs on Windows, macOS, and Linux, but each operation still depends on capabilities of the Dodaios host. A command can exist even when its feature is unavailable there. For example, desktop privacy prompts require the matching desktop operating system, audio commands require host audio devices, and some app-opening actions do not work on a headless server.

The curated command tree never needs the server merely to display help. The dynamic api tree needs either a reachable server or an existing schema cache. An offline cache can explain why help lists an operation that an older or different target does not accept.

How It Fits Together

  1. You choose a curated command or a dynamic api operation.
  2. The CLI resolves the target address and attaches a control key when one is available.
  3. The request enters the same Control API used by other supported control clients.
  4. Dodaios validates the input, checks authentication, and applies server-side safety and permission rules. --yes satisfies only the CLI confirmation gate; it does not bypass those checks.
  5. Dodaios performs the action on its host and returns a result. The CLI renders it as a table or JSON.
  6. If the server, authentication, or host capability is unavailable, the CLI exits with an error instead of inventing a result.

App Commands are the smaller stable catalog shared across voice, chat, desktop, CLI, and REST. The Control API is broader, and the dynamic CLI mirrors that broader surface.

Check That It Works

With Dodaios running, use one read-only command:

dodaios --json system status

The command succeeds and returns JSON with "reachable": true. This confirms that unified CLI routing, local target discovery, authentication, and the server request path are working. It does not test every feature on the host.

Troubleshooting

What you see What it usually means What to do
dodaios --help shows app-launch options Top-level dodaios help belongs to the launcher Use dodaiosctl --help, or ask for help below a control group
Status reports that Dodaios is unreachable The server is stopped, the target is wrong, or authentication failed Start Dodaios, check dodaios auth status, then verify the saved target
The api group is unavailable No schema is cached and the server cannot be reached Start or reconnect to the target, run dodaios refresh, then retry dodaios api --help
A new API operation is missing The dynamic schema cache can remain fresh for 24 hours Run dodaios refresh, then invoke the api group while the intended server is reachable
A dangerous action is refused The CLI requires explicit authorization and never prompts Run the supported --dry-run, review it, then repeat with --yes only if the action is correct

Next Steps