Command line

DataMind Oda usually runs as its own app, and it can also run from a command line. A command-line run is Oda itself, without the app window: it starts one mode, does its work, and exits or keeps serving. Use it to answer one task from a script, to serve the interface to a browser, or to let a program of yours drive Oda.

Start a mode

Each start names one mode with --profile:

oda --profile <name>

Oda ships five modes:

Mode	What it serves	Details
`web`	The Oda interface in a browser on this computer.	Oda in the browser
`headless`	Answers one task, then exits.	This page, below
`sdk`	An Oda SDK client, over standard input and output.	Automation clients
`sdk-minimal`	A small standalone runtime for an SDK client.	Automation clients
`acp`	An automation client that speaks the Agent Client Protocol.	Automation clients

Help starts nothing. -h or --help after a mode name prints that mode's help and exits with code 0, without starting it, and without claiming standard input or output.
A mode's flags come after the profile name. Everything you add on the line belongs to the mode you started.

Run one task and exit

The headless mode answers one task and ends on its own:

oda --profile headless "run the tests"

The task comes as words, joined with spaces into one task. With no words on the line, Oda reads the task from standard input, so a pipe works: git diff --stat | oda --profile headless. A lone - reads standard input as well, and mixing it with words is refused.
A blank task is refused before anything runs. With no task and nothing piped in, the run stops with a task is required, for example: oda --profile headless "run the tests". A task of only spaces is refused too, even when text is piped in.
The answer goes to standard output. The model's reasoning streams to standard error under the oda: reasoning: heading, so a script can read the answer without filtering it.
The exit code tells the outcome. 0 means the task completed. 1 means it did not: the run was aborted or errored, or it finished without an answer; such a run writes an empty line to standard output.
Each run keeps its own chat, saved for later, so a later run can continue it.

Continue a saved chat

Name an earlier chat with --session-id and give the new task:

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

The task runs as the chat's next message. Leave the option out to start a new chat.
An unknown id fails before the task runs: session "<id>" does not exist; omit --session-id to start a new Session.
A blank id stops the run first: --session-id requires a non-empty session id. Otherwise the id is passed on exactly as typed.
The chat must fit the run. Adoption is refused, before the task runs, when the chat is still live in this Oda process, was saved under an agent preset this mode does not run, is a subagent or forked chat, saved no folder, was saved in a different folder than the one you run from, or has damaged records. The chat's saved records and their storage must also be available; without them, the run is refused.
Where the id comes from. A run that reports events opens with a session event carrying the chat's id (see below).

Read a run as JSON events

Add --json to write newline-delimited events to standard output instead of the final answer:

oda --profile headless --json "run the tests"

Event	What it carries
`session`	Opens the stream: the chat's id and the folder the run works in.
`status`	The run's phase: `turn_start`, `step_start`, `step_end` or `turn_end`.
`text`	A piece of the answer, when it is committed.
`thinking`	The model's reasoning, when it is committed.
`tool_call`	A tool the run starts, with its arguments.
`tool_result`	How a tool ended: `completed` or `error`.
`final`	The run's final answer.
`error`	A problem with the invocation itself, such as a bad option or a missing task.

Commit points, not live tokens. Text and reasoning arrive when they are committed, and an attempt that was discarded never reaches the stream.
A failed task still closes with final, and no error event; for a script, exit code 1 and the reason on the closing turn_end are the failure signal.
It is a projection, not the chat's log. The stream shows what the run committed; it is not a copy of the full record.
The stream is bounded. A string or key stops at 8 KiB with truncated: true, and one event line stays under 32 KiB; the final answer is not capped.

The full contract of one-off runs is 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 with MISSING_CREDENTIAL.

Where Oda looks, in order: the environment the run starts in; the saved credential; a .env file in the folder you run from; a .env file in Oda's home folder. Stored credentials covers the lookup order, and Set up models and providers shows how to save a key in the app.
The model list comes from your server. A run can use the models your DataMind account offers; the list is published by your DataMind server.
A restart window. For about 40 seconds after your DataMind server restarts, requests can fail while Oda retries them. If a run still ends in failure, wait a moment and start it again.

Add packages and customise a mode

Add a package. oda plugin --profile <name> add <package> adds a package to a mode; start the mode again afterwards, because a running mode keeps the set of packages it started with.
Your own patch file. --patch <path> lays a patch file of yours over a mode.
Environment values. A mode can also be adjusted through the environment it starts in; these adjustments are meant for deployments.

Oda profiles and launchers covers how a mode is built from its packages, and how your own settings join its layers.

Questions, answered

What can I start from a command line?

Oda ships five modes, one per start: web serves the interface in a browser on this computer, headless answers one task and exits, sdk and sdk-minimal serve SDK clients, and acp serves automation clients that speak the Agent Client Protocol. Name the mode with --profile.

How do I give Oda one task and read the answer?

Start the headless mode with the task: oda --profile headless "run the tests". The answer goes to standard output, the model's reasoning goes to standard error, and the run exits on its own when the task settles.

What happens if I start a run with no task?

Nothing runs. With no task and nothing piped in, the run stops with a task is required, for example: oda --profile headless "run the tests". A task of only spaces is refused too, and the run exits 1 even when text is piped in.

Where do I find the id of the chat a run saved?

From a run's event stream: with --json, the opening session event carries the chat's id. Name that id with --session-id to continue the chat in a later run.

Which chats can a run continue?

Only ones the mode can adopt, and it refuses before the task runs when it cannot: the chat must not be live in this Oda process, must not have been saved under an agent preset this mode does not run, must not be a subagent or forked chat, must have a recorded folder that matches the one you run from, and must have undamaged records and their storage available.

Why do my requests fail with `MISSING_CREDENTIAL`?

The run has no credential for the model yet. Oda looks in the environment the run starts in, then the saved credential, then a .env file in the folder you run from, and last in Oda's home folder. Save the key in the app on Settings > Models, or provide it where the run looks; Stored credentials covers the order.

A run failed right after my DataMind server restarted. What should I do?

Usually nothing. For about 40 seconds after a restart, requests can fail while Oda retries them; if the run still failed, wait a moment and start it again.

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

Add --json. The run writes one event per line to standard output instead of the final answer: session, status, text, thinking, tool_call, tool_result, final, and error for problems with the invocation itself. It is a projection of the run, not the chat's full log.

Can I add a package to a mode?

Yes: oda plugin --profile <name> add <package>, then start the mode again. A running mode keeps the set of packages it started with, so the change applies from the next start. Oda profiles and launchers covers the command and how a mode is built.