Command line and flags

DataMind Oda can be started from a command line: pick a profile, add flags for the mode you want, and Oda reads the line once, before anything starts. Use it to run a mode with other settings, to work with profiles of your own, or to look at the configuration Oda will run.

Oda's own flags

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

The modes themselves, with their own flags, are on Oda in the browser and Automation clients.

How the command line is read

• Oda's flags come first. Oda reads its own flags, and everything after them goes to the app you start; the app parses its own flags, help and exit behaviour from there. Oda's flags must come before the app'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, so one reader cannot take it from another.
• A literal double dash needs the doubled form. A literal -- needs -- --.
• Serving modes end with their input. When Oda serves a client over standard input and output, closing its input ends the process cleanly; Automation clients covers those modes.

Flags beat the configuration

A flag wins over the configuration: oda --profile web --port 8080 serves on port 8080 even when the configuration names another port.

• Even over expressions. The rule holds when the configuration value is written as an expression, not a plain value.
• Resolved once. Flags are resolved when Oda starts, so a later configuration reload never resets a flag.

Help, version and exit codes

• --help prints and exits. It prints the help for the app and exits with code 0, without starting anything.
• --version prints the release version exactly. It reports the version the build carries.
• 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, a port that is not a number reads error: --port must be a number, got "<value>".
• Oda handles this output itself, before the app starts. If a start fails instead of printing help, Startup and diagnostics covers the failure output.

Work with profiles

--profile names the profile for the run: oda --profile web starts the web mode. Oda ships the templates web, headless, acp, sdk and sdk-minimal; the modes themselves are described on Oda in the browser and Automation clients.

• Start from a template. A new profile can start from a shipped template: oda --profile <name> --from-default-profile <template>.
• Profiles live under the Oda home folder, one folder per profile name.
• Manage a profile's packages with the plugin command, for example oda plugin --profile <name> add <package>; managing external packages needs pnpm on your PATH. Oda profiles and launchers covers the command.
• A name Oda does not know is refused. An unknown profile stops the start with profile "<name>" does not exist; create it with 'oda plugin --profile <name> add <package>', and a name Oda cannot use as a profile is refused as invalid profile name "<name>".

Preview the configuration

A config dump prints the configuration Oda will run, composed from its layers. Print it with --dump-config.

• Sources are named. Sections and rows carry # == comments naming their source (# == <label>), and a row that a patch layer changed reads # == <label>, patched by <layers>. For the settings file behind these layers, see The profile settings file.
• Expressions print as written. A value written as an expression appears verbatim.
• Unmatched patches warn. A patch that names an entry the configuration 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 the dump (failed to read config, failed to parse config), and one that is not a top-level list of entries is refused as well.

Check the configuration's schemas

A schema dump prints the schemas the configuration declares, with a status per entry: schema, partial, absent, unsupported or error. Print it with --config-schema-dump.

• No values, no expressions. The schema dump never prints configuration values or the sources of expressions; it shows what the configuration expects, not what is set for it.
• Nothing is started or evaluated. Oda reads the declarations without starting the plugins and without evaluating their expressions.

Questions, answered

Does a flag beat the configuration?

Yes. --port 8080 serves on port 8080 even when the configuration names another port, and the rule holds even when the configuration value is written as an expression. Oda resolves flags once, when it starts, so a later configuration reload never resets a flag.

I reloaded the configuration. Do my flags stay?

Yes. Flags are resolved when Oda starts, and a configuration reload never replaces them; Hot reload covers what a reload does change.

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

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

How do I pass a literal double dash?

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

What do the help and version flags do?

--help prints the help for the app and exits with code 0, without starting anything. --version prints the release version exactly. Oda handles both itself, before the app starts.

Why did Oda refuse my flag value?

When a flag value is not accepted, the app prints its error and exits with a code other than 0. For example, a port that is not a number reads error: --port must be a number, got "<value>". Correct the value, or drop the flag, and start again.

Can I run Oda with a profile of my own?

Yes. Name it with --profile. Oda ships the templates web, headless, acp, sdk and sdk-minimal, and a profile can start from one of them with --from-default-profile <template>. Profiles live under the Oda home folder, one folder per name.

I named a profile Oda does not know. What now?

Oda stops the start and tells you how to create it: profile "<name>" does not exist; create it with 'oda plugin --profile <name> add <package>'. A name Oda cannot use as a profile is refused earlier, as invalid profile name "<name>".

What does the config dump show?

The configuration Oda will run, composed from its layers. Sections and rows carry # == comments naming their source, and rows that a patch layer changed say , patched by <layers>. Expressions print as written. A patch that names an entry the configuration does not have is reported as a warning instead of failing the dump; a configuration that cannot be read or parsed fails it (failed to read config, failed to parse config).

Does the schema dump print my values or expressions?

No. The schema dump lists the schemas the configuration declares, with a status per entry (schema, partial, absent, unsupported or error); configuration values and the sources of expressions are never printed, and Oda reads the declarations without starting the plugins.

Can two parts of Oda read the same command line?

Yes. Oda freezes the command line at startup, so any part of Oda can read it, and reading never consumes an argument for the next reader.