> ## Documentation Index
> Fetch the complete documentation index at: https://isox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell commands

> Run existing tools and package scripts with the built-in core:run-command executor.

`core:run-command` runs a shell command and streams its output to your terminal.
It is included with `@isox-sh/cli`; no separate executor installation is needed.
The fully scoped reference is `@isox-sh/core:run-command`. Both also accept the
plural alias `run-commands`.

## Wrap an existing script

For a project that already has a `build` script in `apps/web/package.json`, create
`apps/web/project.json`:

```json apps/web/project.json theme={null}
{
  "name": "web",
  "targets": {
    "build": {
      "executor": "core:run-command",
      "options": {
        "command": "npm run build",
        "cwd": "apps/web"
      }
    }
  }
}
```

```sh theme={null}
npx isox build web
```

Replace the command with your package manager or underlying tool invocation.
Make sure the wrapped script does not call the same Isox command recursively.

## Options

| Option | Required | Behavior |
| - | - | - |
| `command` | Either `command` or `commands` | Nonempty shell command string |
| `commands` | Either `command` or `commands` | Nonempty array of strings or `{ "command": "..." }` objects |
| `parallel` | No | Run array entries concurrently (default `true`); `false` runs them in order |
| `cwd` | No | Working directory, relative to the workspace root or absolute; defaults to the workspace root |

Commands inherit the environment and standard input, output, and error streams.
A nonzero exit code or signal termination fails the Isox command. Cancellation
propagates to the child process tree.

## Run multiple commands

```json theme={null}
{
  "executor": "core:run-commands",
  "options": {
    "commands": ["node scripts/prepare.mjs", "npm run build"],
    "parallel": false,
    "cwd": "apps/web"
  }
}
```

Use exactly one of `command` or `commands`. Every entry runs in its own shell
with the same `cwd`; changing directories in one entry does not affect another.
Entries run in parallel by default. Set `parallel: false` to run them in order.
A failed command stops the sequence or cancels parallel siblings. The executor
waits for all child processes to finish before returning.

String entries and command objects execute the same way. For example, this array
uses both forms:

```json theme={null}
{
  "commands": [
    "npm run lint",
    { "command": "npm run test" }
  ]
}
```

Command objects accept only `command`; set `cwd` and `parallel` on the enclosing
options object. Put each tool's arguments directly in its command string.

## Configure tool flags

Put tool flags in `command`. Use named configurations for repeatable variants.
A configuration or CLI options override can switch between `command` and
`commands`; the explicitly supplied form replaces the inherited form. Supplying
both together in the same override is invalid.

For example, `isox check web --strict` would pass an option named `strict` to this
executor; it would not append `--strict` to your shell command. Define the full
command in the configuration instead:

```json theme={null}
{
  "executor": "core:run-command",
  "options": {
    "command": "node scripts/check.mjs"
  },
  "configurations": {
    "strict": {
      "command": "node scripts/check.mjs --strict"
    }
  }
}
```

If this definition is stored under `targets.check`, run
`isox check web --config=strict`. The example assumes your workspace provides
`scripts/check.mjs` and that it accepts `--strict`.

The executor passes command strings to the shell without expanding workspace
tokens or loading `.env` files. The invoked tools handle their own configuration.
Use target-level
[`dependsOn`](https://isox.sh/docs/task-prerequisites#task-prerequisites) for required build ordering.

For programmatic execution and cancellation helpers, see the [core API](https://isox.sh/docs/core-api.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.