Shell commands

While DataMind Oda works on a task, it sometimes runs a command on your computer: a small program in Bash or PowerShell that starts, does its work, returns its output, and ends. This page covers how those commands run, how each one appears in your chat, and how to read what comes back. Your own terminal in the side panel is a separate surface, described in The terminal.

Ask Oda to run a command

• You ask in your own words, for example to check the free space on a disk or to tidy a folder. Oda writes the command and runs it for you.
• Oda uses Bash or PowerShell, whichever fits your computer.
• Oda writes a short description, in the active voice, for every command it runs, so the step reads clearly in the chat.
• Each command is a fresh run. Nothing carries over from the command before it: not the folder it ran in, not the variables it set, and not the functions it defined. When a task needs to keep its folder and settings between commands, Oda can use a shell that stays alive; see Persistent shells.
• A run is not interactive: nothing can type into a command while it runs.
• Oda can give a command a folder to run in and a time limit to work within. What a command may change on your computer is set by the chat's access mode; see Command sandboxing and approvals. The shell Oda picks, the limits and the variables every command receives are on Command environment and containment.

The command in the chat

Each command appears in the chat as a step row: a one-line summary to scan, and a terminal card to expand for the output. The general model of step rows is described in Oda's steps and tool results.

• The collapsed row carries the short description Oda wrote for the command, or the command itself when no description is recorded.
• While the command runs, the row shows a running state. When it settles, the row shows how it ended: a command that ended with a non-zero exit code or a signal is shown as failed, even though the step itself settled.
• The row also carries its state as hidden text for screen readers: running, failed or stopped.

To read the card:

1. Click the row, or select it and press Enter or Space. The same action collapses it again.
2. The card shows the command that ran: each command line gets its own prompt row.
3. The full output sits in a scrolling area inside the card, never cut off in the middle. Scroll inside the card to read it all; the command's description stays visible while you do.
4. A run-state indicator shows where the command stands: running while it works, done once it settles. A command that failed still reads done on the card: the card says the command finished, the row says how it ended.
5. The copy control on the card copies its recorded content, ready to paste elsewhere.

The card also shows the working folder the command ran in, tidied for reading: an absolute folder is shown as it is, and a relative one is resolved under the chat's workspace folder. . and .. are collapsed, and a path that climbs above the drive's root is dropped. A network share keeps its full root.

When the card cannot be drawn from the recorded result, the row falls back to simpler forms:

• Very long results. A result too big to keep in the chat is stored separately; its row shows the plain block with IN (the command as recorded) and OUT (what came back), and never shows an exit-code pill.
• Background starts. A command that Oda starts in the background shows a short acknowledgement row that stays collapsed: there is nothing to expand there.
• Persistent shells. While a persistent-shell command runs, its card is shown; once it settles, the plain block is shown instead.
• Unusual records. If the recorded data cannot be drawn as a card, the row stays plain, showing the recorded input and output.

When Oda sends input into a running terminal, the row names the terminal it wrote into, for example Terminal pty-3. A send that carries no text of its own reads (send input).

How to read a result

When a command ends, its result carries the 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 it ended. The notes you may see:

• Oda checks the ending note on every result, and looks into a failure before moving on.
• On the terminal card, the ending is shown as the card's own exit pill, and the exit marker is removed from the shown output. A result with no marker reads as exit 0. Other bracketed notes stay in the output, for example a note that the command timed out. When a command produces no output, the card says so instead of showing an empty space.
• 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 and notes it: [output truncated; full output: <path>], or [some output was dropped from memory; full output: <path>] when the app had to drop part of the output before it was read. The full text, up to 64 MiB, is saved to the file the note names; ask Oda to open it, or to search inside it, when you need the rest.

Commands that move to the background

When a command is still running at its time limit, Oda does not kill it. The command moves to a background job and keeps running while the chat carries on. The limit is two minutes by default, and Oda can give a single command up to ten minutes.

• 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.
• A command Oda starts in the background on purpose reports its start as started background job <id>.
• When the job finishes, the notice reads finished [status: completed, exit code: 0], and Oda collects what came back. A later read returns only newer output; what was already collected is not repeated.
• A job reads as running while its command works, as completed when it ends on its own, and as killed when it is stopped. A non-zero exit 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 background job belongs to the chat that started it. Read from another chat, it is refused, and Oda reports belongs to another session. 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 one, 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.

Commands 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 a failure the command reported.
• Before running a command, 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.

Questions, answered

Does each command start fresh?

Yes. Every command is a fresh run, so the folder it ran in and the variables it set do not carry over to the next command. For a task where each command should build on the one before, Oda keeps a shell alive instead; see Persistent shells.

Why did my command keep running after its time limit?

Oda does not kill a command at its time limit. Instead, it hands the command over to the background as a job, so the command keeps running while the chat carries on. The step reports the hand-over, and Oda is told when the job finishes. The limits applied to commands are described in Command environment and containment.

How do I follow a command that moved to the background?

Ask Oda for its output. Oda reads newer output with job_output, and when the job finishes the notice reads finished [status: completed, exit code: 0]. A read returns only what has arrived since the last one.

How do I stop a command that is still running?

Press Stop in the message box while the step runs, or ask Oda to stop the background job with job_kill. A command stopped from outside reads [stopped: <reason>], with the reason saying why, and Oda does not retry it on its own.

Why does a command show as failed when the step itself completed?

Because the command itself ended with a non-zero exit code or a signal, and Oda reports that on the row. The step still settles, and the card still reads done: the card says the command finished, the row says how it ended.

Why is there no exit code on a very long command's result?

A result too big to keep in the chat is stored in a file, and its row shows the plain IN and OUT block instead of a terminal card. Those blocks never show an exit-code pill; ask Oda to read the stored result if you need to check the ending.

Why can't I expand a background command?

The row for a background start is only an acknowledgement, not a result: it stays collapsed and has nothing to expand. The command runs on while the chat continues; ask Oda for its output.

Why is the background option not offered here?

Background runs are switched off in this installation. The option is not offered, 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.

Why did a stopped PowerShell command report exit code 1?

On Windows, a command that is force-stopped has no signal to report, so it reads [exit code: 1]. That is how an interruption shows there, not a failure that the command reported.

Why does a PowerShell script that starts with param(...) fail?

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; the script works when kept in a file and run from there, or wrapped in a block.

Why does the result say part of the output was dropped?

The command produced more output than the result keeps. Oda saves the full text to a file, and the note names it: the note says the output was truncated, or that some of it was dropped from memory. Ask Oda to open the file, or to search inside it, when you need the missing part.

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 it was stopped before the command was sent, the report reads tool call aborted before dispatch instead. Ask Oda to run it again if you still need it.