The Oda command line

DataMind Oda usually runs as the desktop app, and it can also run from a command line. A command-line run starts one profile, and flags on the same line adjust how that run behaves. This page is the reference for how Oda reads that line: the flags, what wins when a flag and the settings file disagree, and what the help and error output do.

Start a profile

A command-line run starts one profile, and the profile name decides which setup the run uses. Name the profile on the command line when Oda starts.

• Shipped templates. Oda ships five profile templates: web, headless, acp, sdk and sdk-minimal; Oda profiles and launchers describes what each serves.
• Start from a template. A new profile can start from a shipped template, named on the line when the profile first starts.
• Where profiles live. Profiles live under the Oda home folder, one folder per profile name; Oda's home folder and settings files covers the folder.
• Refused names. A name Oda cannot use as a profile is refused as invalid profile name "<name>"; a name that does not exist yet stops the start (profile "<name>" does not exist), and the message names the plugin command that creates the profile.
• Packages. A profile's packages are managed with the plugin command.

Flags and the settings file

A flag wins over the matching value in the settings file: --port 8080 serves on port 8080 even when the settings name another port.

• Even beside an expression. The rule holds when the settings value is written as an expression, not as a plain value.
• Resolved once. Flags are read when Oda starts, so a later settings reload never resets them; Hot reload covers what a reload does change.

Oda's flags and the app's arguments

• Oda's flags come first. Oda reads its own flags, and everything after them goes to the app the profile starts, which parses its own flags from there. Keep that order: Oda's flags before the app's arguments.
• The line is frozen. Oda takes the command line once, 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 -- needs the doubled form, -- --.

Help and exit codes

• --help prints and exits. It prints the help for the app and exits with code 0, without starting anything.
• A refused value exits non-zero. When the app 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>".
• Handled before the app's work. Help, version and error output are handled by the launcher itself, before the app's own work begins.
• A failed start is different. When the start fails rather than printing help, Startup and diagnostics covers the output and the exit code.

Look at a profile's configuration

Oda can show what a profile will run, without starting it.

• The configuration dump. --dump-config prints the settings as Oda composes them from their layers, with each source named in comments: # == <label>, or # == <label>, patched by <layers> when a later layer changed the row. A patch that names an entry the setup does not have is skipped with a warning and the dump still prints; a configuration that cannot be read or parsed stops the dump instead.
• The schema dump. It prints the schemas the entries declare, with a status for each: schema, partial, absent, unsupported or error. It never prints configuration values or the sources of expressions.
• Command line and flags covers both dumps in more depth.

Questions, answered

How do I start Oda from a command line?

Name the profile for the run on the command line. A command-line run starts one profile, and the shipped templates are web, headless, acp, sdk and sdk-minimal; Oda profiles and launchers describes what each serves.

Where do profiles live on this computer?

Under the Oda home folder, one folder per profile name. Oda's home folder and settings files covers how the folder is chosen and shown.

How do I start a new profile from a shipped template?

Put the shipped template on the line when the new profile starts. The shipped templates are web, headless, acp, sdk and sdk-minimal.

Why did a flag win over the settings file?

A flag beats the matching value in the settings file: --port 8080 serves on port 8080 even when the settings name another port. The rule holds when the settings value is written as an expression, and flags are resolved once, when Oda starts.

Do my flags survive a settings reload?

Yes. Flags are resolved once, when Oda starts, and a later settings reload never resets them. Hot reload covers what a reload does change.

How do I pass a literal double dash?

Write it doubled: -- --. A literal -- needs that form.

Why did the start exit with a code other than 0?

A flag value was refused. The app prints its error and exits with a code other than 0; error: --port must be a number, got "<value>" is one such message. Correct the value, or drop the flag, and start again.

Does --help start anything?

No. --help prints the help for the app and exits with code 0, without starting anything. Help, version and error output are handled by the launcher, before the app's own work begins.