Bash and PowerShell command tools

While DataMind Oda works on a task, it runs commands on your computer, in bash or PowerShell. Each command is a single run that starts, does its work, returns its output and ends; this page describes how those runs behave and how to read what comes back.

A command from start to finish

• You ask in your own words, and Oda writes the command and runs it for you. Oda sends a short description of every command, in the active voice, so the step reads clearly in the chat.
• Each command is a fresh run. The folder, the variables and the functions of one command do not carry over to the next. For work that needs the same folder and variables between commands, Oda can keep a shell alive; see The persistent bash shell.
• Oda can give a command a folder to run in, and a time limit to work within.
• A run is not interactive: nothing can type into a command while it runs.
• What a command may change on your computer is set by the chat's access mode; see Sandboxing and command limits.

How to read a result

The result carries the command's output: the ordinary output first, then a [stderr] section with the error output when the command has any. A short note at the end says how the command ended:

• Oda checks the ending note on every result, and looks into a failure before moving on.
• On the chat's terminal card, the ending is shown as the card's own exit pill, and the exit marker is removed from the shown output. Commands Oda runs describes the row and the card in full.
• A command that moves to a background job instead of being stopped reports the hand-over instead; see Commands that keep running below.

When the result is cut short

• The result keeps up to 64,000 bytes of a command's output. When a command produces more, the result keeps the most recent part of the output and carries a note naming a file that holds the full text, up to 64 MiB: [output truncated; full output: <path>].
• When a background job's earlier output had been dropped before it was read, the read says [some output was dropped from memory; full output: <path>] and names the file the complete text was saved to.
• Ask Oda to open the file the note names, or to search inside it, when you need the rest.

Commands that keep running

• Every command has a time limit: two minutes by default, and Oda can give a single command up to ten minutes. The command environment describes the limits and where they can be changed.
• A command that outlives its limit is not killed. It moves to a background job and keeps running while the chat carries on. The step reports the hand-over: [still running after <n>ms; moved to background job <id>], with the note that the command keeps running, that Oda is told when it finishes, and that Oda reads newer output with job_output and stops the job with job_kill.
• Oda can also start a command in the background on purpose; the start reports started background job <id>. While it runs, ask Oda for its output, or to stop it; a later read returns only what has arrived since the last one.
• When the job finishes, Oda is told with a notice that reads finished [status: completed, exit code: 0].
• A job reads as running while its command works, as completed when it ends on its own, and as killed when it is stopped. Its details say how it ended, for example exit code: 0; a non-zero code still counts as completed, because the command did finish. A stopped job reads killed before exit, or names the signal that ended it.
• A job belongs to the chat that started it and is read from there. Background jobs: limits and lifecycle describes how jobs are owned, kept and limited.

When a command cannot run

• If background runs are switched off in this installation, Oda does not offer them, and a request that still asks for one is refused with run_in_background is disabled for this deployment. Ask Oda to run the command in the foreground instead; its time limit applies as usual.
• If the background support is not loaded at all, Oda reports that background jobs are unavailable, and the command can still run in the foreground.
• If a step is stopped before the command is sent, Oda reports tool call aborted before dispatch. A step stopped while its command runs reports tool call aborted, and the command does not continue.
• If a command cannot start at all, the result carries a note that the failure happened before the command reported an outcome.

On Windows

• Oda runs commands in PowerShell on Windows. A command that the system force-stops reports [exit code: 1] and no signal; treat it as an interruption, not as a result the command reported. Signals such as [killed by signal: X] are reported on macOS and Linux.
• Before a command runs, Oda sets up its text handling, and that setup comes before the command itself. A script whose first statement must come first, such as param(...), #requires or using, cannot run as written; it works when wrapped in a block, or kept in a file and run from there.
• On a computer where Oda uses Windows PowerShell 5.1, input that is not plain ASCII can be decoded incorrectly.

What every command runs with

• Colour and paging are turned off so results are readable text: NO_COLOR=1, PAGER=cat and GIT_PAGER=cat are set, bash also sets TERM=dumb, and PowerShell output is pinned to UTF-8.
• A small set of managed variables points at the facts Oda works with: DATAMIND_HOME (the folder Oda keeps its data in), DATAMIND_SHELL (set to 1) and DATAMIND_SESSION_ID (the chat the command belongs to); a profile adds DATAMIND_PROFILE and DATAMIND_PROFILE_DIR. Use them in your own scripts.
• The command environment lists every variable and the limits each command runs under.

Questions, answered

What does [exit code: N] mean on a result?

It is the code the command itself reported when it finished. Zero means it succeeded; any other number means the command reported a failure. Oda reads the note on every result and looks into a failure before moving on.

Why did a command end with [killed by signal: X]?

A signal ended the command before it could exit on its own. Signals are reported on macOS and Linux; on Windows, an interrupted command reports [exit code: 1] instead. If the command's work still matters, ask Oda to run it again.

What does [stopped: <reason>] mean?

The command was stopped from outside its own run, for example when you stop the step or its job, and the reason says why. Oda reads it as a stop, not as a failure of the command, and does not retry the command on its own.

What does a result of (no output) mean?

The command finished without producing any output. If you expected output, ask Oda to check what the command did, or to run it another way.

Where can I find the full output when a result is cut short?

The full text is saved to the file the note names; ask Oda to open that file or to search inside it. This holds for both a cut result and a background read that dropped part of the output.

What happens when a command runs longer than its time limit?

It is not killed. It moves to a background job and keeps running, and the step reports the hand-over; Oda is told when the job finishes. The default limit is two minutes, and Oda can give a single command up to ten minutes.

How do I get the output of a command that moved to the background?

Ask Oda for it. Oda reads newer output with job_output and can stop the job with job_kill; each read returns only what has arrived since the last one, and Oda is told when the job finishes.

What does tool call aborted mean?

The step was stopped before it could finish, so it has no result and the command does not continue. If the step was stopped before the command was sent, the report reads tool call aborted before dispatch instead. Ask Oda to run the command again if you still need it.

Why does a force-stopped command on Windows report [exit code: 1]?

On Windows an interrupted command has no signal to report, so it reads as exit code 1. Treat it as an interruption, not as a failure the command reported, and ask Oda to run it again if the work still matters.

Why can't a PowerShell script start with param(...)?

Before a command runs, Oda sets up its text handling, and that setup comes before the command itself. A first statement that must come first, such as param(...), #requires or using, cannot run that way; wrap the script in a block, or keep it in a file and run it from there.

What variables can commands receive from Oda?

DATAMIND_HOME (the folder Oda keeps its data in), DATAMIND_SHELL (set to 1), DATAMIND_SESSION_ID (the chat the command belongs to), and DATAMIND_PROFILE and DATAMIND_PROFILE_DIR when a profile is set. Use them in your own scripts; The command environment lists them all.