CLI reference

Install @isox-sh/cli to get the isox binary. The examples below use isox; for a local installation, run npx isox, pnpm exec isox, or yarn isox.

Commands

Command	Behavior
`isox init`	Create `isox.json` in the current directory
`isox init <package> <path> [--importPath=<name>]`	Scaffold a project using an installed package inside an existing workspace
`isox add <package> <project>`	Run an installed plugin’s add generator on an existing project
`isox <command> <project>`	Run a project’s configured command
`isox run <project>:<command>`	Alternative syntax, including commands whose names are reserved by the CLI
`isox affected --target=<command>`	Run changed projects and their dependents; add `--print-matrix` for a JSON project array
`isox plan --target=<command> --max-jobs=3`	Print an affected, weighted GitHub Actions matrix; use `--all` to select every matching project
`isox run-many --target=<command> --projects=core,cli`	Run selected projects with optional `--parallel`
`isox migrate <version\|latest>`	Update Isox dependencies and generate a migration plan
`isox migrate --run-migrations [file]`	Run a reviewed migration plan after installing dependencies
`isox reset`	Remove `.isox`; definitions and dependency analysis are recreated when next requested
`isox --help`	Show usage

In isox build web, build is the target name and web is the project name. Use isox run web:build when you prefer an explicit reference, or when the target name conflicts with a built-in CLI command such as add or init.

Executor option overrides

Use --verbose for debug logging and error stacks. Execution commands forward unknown flags to the executor as option overrides:

isox lint my-app --fix --max-warnings=5
isox run my-app:lint --no-fix
isox run-many --target=lint --fix
isox affected --target=lint --fix

Hyphenated names become camelCase (--max-warnings becomes maxWarnings). Bare flags are true, --no-<name> is false, numeric values become numbers, and repeated flags become arrays. Executors may validate the options they support. Isox’s own flags, such as --verbose, --config, and --parallel, stay with the CLI. init, add, migrate, reset, and plan reject unknown flags. Use --options for a JSON object when values need explicit types, nested objects, or names that overlap with CLI flags:

isox build my-app --options '{"release":"001","settings":{"minify":true}}'

Forwarded executor-option flags take precedence over --options. Reserved CLI flags do not override executor options: for example, run-many --parallel=4 with --options '{"parallel":2}' runs up to four projects concurrently while passing parallel: 2 to each executor. In multi-project execution, overrides apply only to the requested target; pre/post targets keep their own options.

Pre and post stages

For affected, plan, and run-many, --pre-targets and --post-targets accept comma- or newline-separated command lists. Use --pre-targets-json and --post-targets-json for exact arrays, including command names that contain commas. For example, --pre-targets-json '["prepare,assets:acc"]' runs prepare,assets with its acc configuration. Do not combine a list flag with its JSON counterpart. See affected projects and CI for stage ordering.

Task output

run-many and executing affected show a live progress footer in interactive terminals. It lists running tasks with elapsed times and counts pending, completed, failed, and cached tasks, plus a completion bar. Cyan indicates running work, green indicates success, and red highlights failures and their diagnostics. Results are indented beneath the stage heading; diagnostics are indented beneath the failed task. Colors respect NO_COLOR, FORCE_COLOR, and terminal support. Completed results stay above the footer:

   ✔ isox run api:build:production (1.25s)
   ✔ isox run web:build:production [local cache]

   Successfully ran target build for 2 projects (1.30s)
   1/2 tasks read from cache

Successful tool output is hidden by default outside GitHub Actions. Failed and cancelled tasks print their captured diagnostics beneath their result; large output is truncated with an explicit notice. The final summary includes failures, cancellations, and tasks that never started. CI, redirected output, and ISOX_PROGRESS=0 use the same compact task results, cache labels, failure diagnostics, and summaries without cursor animation. In GitHub Actions, every completed task gets a collapsible log group such as ✅ > isox run api:build (1.25s) or ❌ > isox run web:build (failed after 1.25s). Expand the group to inspect that task’s captured stdout and stderr, including successful and cached output. Parallel tasks publish complete groups so their logs stay separate. Large logs retain their bounded tail with a truncation notice. Use --verbose to list the selected projects and stream all tool output with detailed lifecycle messages instead of buffering it into groups.

Named configurations

Commands can define named option overrides in configurations and select a fallback with defaultConfiguration. For example, a command definition can be:

{
  "executor": "@isox-sh/core:run-command",
  "options": {
    "command": "node scripts/build.js",
    "cwd": "."
  },
  "defaultConfiguration": "development",
  "configurations": {
    "development": {},
    "production": { "command": "node scripts/build.js --production" },
    "staging": { "command": "node scripts/build.js --staging" }
  }
}

Use your own build script and select a configuration with:

isox build my-app --prod
isox build my-app --config=staging
isox run my-app:build --configuration production
isox build my-app -c staging

--prod selects production. --config, --configuration, and -c are aliases; an explicit name takes precedence over --prod, then defaultConfiguration applies if neither selects a name. Without any selection or default, only base options are used. An unknown configuration fails with an error. Names retain their exact spelling, including leading zeros in names such as 001. Options are merged at the top level: { ...options, ...configurations[name], ...cliOverrides } after workspace target defaults are merged. Nested objects and arrays are replaced rather than recursively merged. This works with native and Nx executors, including automatically migrated Nx project files. The source configuration and workspace cache retain their original values; the selected options are computed for each invocation. Only one configuration can be selected per invocation. Executor CLI flags override the selected configuration.

Workspace cache

Isox keeps project definitions, dependency analysis, and task results in .isox:

Cache	Purpose	When it refreshes
`workspace.json`	Project definitions and merged target defaults	`affected`, `plan`, and `run-many` refresh it; single-project commands reuse it
`discovery.json`	Inferred dependencies	Validated for Git-based `affected` / `plan` selection, task caching, output ordering, or an executor that needs dependencies
`tasks/`	Successful task results	Used by native targets with `cache: true`

affected --all, plan --all, and ordinary run-many selection do not infer dependencies. Execution can request analysis separately for task caching, ordering selected projects with cached outputs, or executor needs. After editing project definitions, target defaults, or discovery rules, run isox reset before a single-project command. Source and import edits do not require a reset. A dependency-analysis cache hit alone does not skip execution. Use --skip-cache to bypass task-result reads and writes. Before running isox reset, stop active builds and recover any needed interrupted-task backups from .isox/tasks. Reset removes all of .isox, including those backups, task results, TypeScript output ownership records, and build locks. Compiled output stays in place. See output recovery. See cache behavior and invalidation and task caching for details.

Current scope

Affected selection follows inferred and explicitly declared dependencies. Parallel execution uses separate child CLI processes, and the GitHub actions distribute exact weighted project lists. See affected projects and CI. Cached builds with declared outputs wait for selected dependencies, even with --parallel=1. Independent projects can run concurrently. Targets with dependsOn expand required tasks outside the selected project list, within each worker’s checkout. Local task caching is opt-in; remote caching and isolation remain on the roadmap.

Upgrade Isox

See Updating Isox and running migrations for the plan, review, install, and run workflow, including custom plans and retries.

Publish migration scripts

See publishing migration scripts for the package registry format, migration API, and build configuration.

CLI and configuration

Workspace internals

Contribute to Isox