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, 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 clients.

• 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.
• 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.
• A literal double dash. A literal -- argument needs the doubled form -- --.

How a profile stacks its layers, and what the other flags do, are on Oda profiles and launchers and Command line and flags.

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; with no words, Oda reads it from standard input, and a lone - reads standard input too.
• The answer goes to standard output; 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.
• Each run keeps its own chat, saved for later.

The full contract, including the JSON event stream: 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 subagent 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 refusals in full are on Headless runs.

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. 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, with a comment on each row naming the layer it came from and any overlay that changed it.
• --dump-default-config prints only what Oda ships, without your own layers.
• --dump-config-schema prints the declared schemas instead of values. 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 prints that mode's help instead and starts nothing; the flags after a profile name belong to the mode you start.
• -V, --version prints the release version.

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.

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.