DataMind Oda on the command line

DataMind Oda usually runs as the desktop app, and it can also run from a command line. Use the command line to start Oda in a named profile: serve its interface in a browser, answer one task and exit, or host a client of your own.

Start a profile

A command-line Oda runs in a profile: a named setup of Oda that decides how that run works. Each profile keeps its own folder under the Oda home folder, one folder per profile name, and starting the same name again reuses that setup.

Start one from a terminal:

oda --profile web

Oda ships five profiles:

The serving profiles and their clients are described on Automation with Oda.

• First use creates it. Each shipped profile sets itself up from the template Oda ships, so you do not prepare the five names by hand.
• Your own name. Copy a shipped template into a name of your own with --from-default-profile <template>, for example oda rescue --from-default-profile web, then start oda rescue. A name that is already shipped or already exists is refused.
• An unknown name is not created by itself: the start stops with profile "<name>" does not exist and points to the command that adds a package to that name.
• A name Oda cannot use as a profile is refused as invalid profile name "<name>".
• The desktop app's name is reserved. The desktop app runs under the profile name desktop; starting it, inspecting it or managing its packages from a command line is refused, because the app manages that profile.
• One profile per start. Selecting a profile twice is refused: select a profile only once.
• Extra layers. --patch <path> lays one of your own files over the profile; it needs a path, or Oda stops with error: --patch needs a path. How a profile stacks its layers is on Oda profiles and launchers.

How Oda reads the command line

Oda reads a small set of flags of its own, and every mode adds its own flags on top.

• Oda's flags come first. Oda reads its own flags, and everything after them goes to the mode you start, which parses its own flags, help and exit behaviour from there. Keep that order: Oda's flags before the mode's arguments.
• Read once, then frozen. Oda takes the command line at startup and freezes it. Any part of Oda can read the frozen line, as often as it needs; reading never consumes an argument.
• A literal double dash. A literal -- argument needs the doubled form -- --.
• A flag beats the settings. oda --profile web --port 8080 serves on port 8080 even when the settings name another port, and the rule holds when the settings value is written as an expression.
• Flags are resolved once. They are read when Oda starts, so a later settings reload never resets them; Hot reload covers what a reload does change.
• A refused value exits non-zero. When the mode rejects a flag value, it prints its error and exits with a code other than 0, for example error: --port must be a number, got "<value>". When a start fails instead, Startup and diagnostics covers the output and the exit code.

Run one task and exit

The headless profile answers one task and exits, without opening the app:

oda --profile headless "summarise the latest changes"

• The task comes as words on the line, joined with spaces into one task. With no words, Oda reads it from standard input, so a pipe works: git diff --stat | oda --profile headless. A lone - reads standard input too, and mixing it with words is refused.
• The answer goes to standard output; reasoning (under a heading line that ends reasoning:) and any problems go to standard error, so a script can read the answer cleanly.
• The exit code is 0 only when the run completed; any other outcome exits 1, including a run that produced no answer. Such a run writes an empty line to standard output.
• A start with no task and nothing piped in is refused before anything runs, with a message that a task is required. A task of only spaces is refused too, even when text is piped in.
• Each run keeps its own chat, saved for later.
• Events instead of an answer. Add --json to write newline-delimited events to standard output instead of the final answer. The stream opens with a session event that carries the chat's id.

The full contract, including the JSON event stream and its bounds: Headless runs.

Continue an earlier run

Name an earlier chat with --session-id, plus the new task:

oda --profile headless --session-id <id> "carry on with the task"

• The id goes as typed. A blank id exits 1 before anything runs.
• An id Oda does not know fails before the task runs, and points you to start a new chat by leaving the option out.
• Adoption can be refused when the chat is still running here, is a sub-agent or branch chat, saved no folder or a different folder, runs under an agent preset this mode does not run, or has damaged records. The chat's saved records and their storage must also be available.

The refusals in full are on Headless runs.

Model access for command-line runs

A run needs a model credential before it can answer; until one resolves, model requests fail. Sign in to your DataMind server, or save a key on Settings > Models (Set up models and providers). Where Oda looks for a credential, and in which order, is on Stored credentials. A run can use the models your DataMind account offers.

Manage a profile's packages

A profile's packages are managed by the plugin command:

oda plugin --profile <name> add <package>

• Add, remove, update. The command forwards its arguments to the package manager inside the profile's folder, so add, remove and update work the same way.
• After a successful change, Oda updates the profile's layers: a package that carries a settings document joins the profile's layers, and a package that carries none stays an ordinary dependency.
• Restart the profile. A running profile keeps the set of packages it started with, so start it again after a change.
• A package that builds while installing can stop the first install: the package manager blocks that build until you allow it. The command prints the exact setting to add to the settings file inside the profile's folder; add it, then run the command again.
• The package manager must be available. Managing external packages needs pnpm on your PATH; the command reports when it is not installed or not on your path.

The same command is walked through on Oda profiles and launchers.

Look at the configuration

Oda can show what a profile will run, without starting anything:

• --dump-config prints the settings as Oda composes them from their layers. Sections and rows carry comments naming their source, # == <label>, or # == <label>, patched by <layers> when a later layer changed the row. Expressions print as written. For the file behind these layers, see The Oda settings file.
• Unmatched patches warn. A patch that names an entry the setup does not have is reported with its layer label and skipped; the dump still prints.
• A broken configuration fails the dump. A configuration that cannot be read or parsed stops it (failed to read config, failed to parse config), and one that is not a top-level list of entries is refused as well.
• --dump-default-config prints only what Oda ships, without your own layers.
• --dump-config-schema prints the schemas the entries declare instead of values, with a status for each: schema, partial, absent, unsupported or error. It never prints configuration values or the sources of expressions. Nothing starts and no expressions are evaluated, but the output can still contain sensitive defaults: Review output before sharing.
• One at a time. The three options are mutually exclusive, and a dump takes no arguments meant for the app.

Serve the browser interface

oda --profile web serves the Oda interface to a browser on this computer, prints its address, and opens that address in your default browser. Started over a remote connection, Oda prints the address and skips the handoff.

• --no-open starts it without opening a browser; the address still prints.
• It listens on this computer only. The address uses 127.0.0.1, and binding every network interface is refused for safety.
• --host, --port, --trusted-host change the bound host, the port, and any extra hostname you reach the interface under.

Starting it and signing in: The Oda web interface; working in the browser: Oda in the browser.

Help without starting

• oda --help prints the launcher's own help and exits without starting anything.
• oda --profile web --help (or -h) prints that mode's help instead, exits with code 0 and starts nothing, without claiming standard input or output; the flags after a profile name belong to the mode you start.
• -V, --version prints the release version exactly.
• Handled before the mode's work. Help, version and error output are handled by the launcher itself, before the mode's own work begins.

Stop a running profile

Press Ctrl+C to ask Oda to stop: it gets up to five seconds to settle, then stops. If it has not stopped yet, press Ctrl+C again to end it at once; an end you ask for this way reports exit code 130.

Questions, answered

What is a profile?

A named setup of Oda that decides how a run works: which layers Oda stacks and which of your own settings apply. Each profile lives in its own folder under the Oda home folder, and starting the same name again reuses the same setup.

What happens the first time I start a shipped profile?

Oda sets it up from the template it ships and then starts it, so you do not prepare the five shipped names by hand. Any other name is not created by itself: the start stops and points to the command that adds a package to that name.

Can I leave out --profile?

Yes, when the profile name is the first word: oda web means oda --profile web. One word is special: plugin in the first position is the plugin command, so a profile named plugin needs the full form, oda --profile plugin.

Why is the profile name desktop refused?

That name belongs to the desktop app's own profile, and the app manages it. Starting it, inspecting its configuration or managing its packages from a command line is refused, so pick another name for a profile of your own.

How do I stop a command-line Oda?

Press Ctrl+C. Oda gets up to five seconds to settle and then stops; a second Ctrl+C ends it at once. An end you ask for this way reports exit code 130.

Why did my package install ask for a build approval?

Some packages build while they are installed, and the package manager blocks that build until you allow it. The command prints the exact setting to add to the settings file inside the profile's folder; add it, then run the command again.

What does select a profile only once mean?

Oda reads the command line once, and it selects a profile only once: a second --profile is refused with that message. A --patch without a path is refused the same way: error: --patch needs a path. Fix the line and start again.

Why did a flag win over the settings file?

A flag beats the matching value in the settings: --port 8080 serves on port 8080 even when the settings name another port, also when that value is written as an expression. Flags are resolved once, when Oda starts, so a settings reload never resets them.

Where do Oda's flags end and the mode's arguments start?

Oda's own flags come first, and everything after them goes to the mode you start, which parses its own flags from there. Keep that order: Oda's flags first, then anything meant for the mode.

Does the schema dump print my values or expressions?

No. --dump-config-schema lists the schemas the configuration declares, with a status per entry (schema, partial, absent, unsupported or error). Values and the sources of expressions are never printed, and nothing is started. Defaults can still be sensitive, so review the output before you share it.

How do I get machine-readable output from a run?

Add --json to a headless run. It writes one event per line to standard output instead of the final answer, opening with a session event that carries the chat's id. Headless runs lists the events and their bounds.

Can I start the web interface without opening a browser?

Yes: add --no-open. Oda still prints the interface's address, so you can open it yourself or copy it to a browser. The Oda web interface covers the printed address.