name	nixo-cli
description	Use when requests involve nixo or nixosandbox sandbox lifecycle operations, catalog queries, session-id workflows, or CLI errors such as 'Could not find flake.nix' and create flag conflicts.

nixo CLI

Use this skill for runtime-agnostic workflows around the nixo command line.

When not to use

Do not use this skill for Nix flake authoring or package derivation work unless the task explicitly centers on the nixo CLI workflow.
Do not use this skill when the user only needs raw nix build, nix develop, or bubblewrap commands outside a sandbox session flow.
Do not use this skill when another repo-local workflow overrides the CLI, such as project-specific wrapper scripts or extension-only APIs.

Naming

Use nixo as the default command in all new instructions, prompts, and automation.
Use nixosandbox only when the user explicitly asks for the legacy name or when nixo is unavailable.
Keep flags and behavior identical across both names.

Core workflow

Discover available packages with catalog.
Create a sandbox with create, using --with for package lists or --profile for named presets.
Use --json when the output will be parsed by another tool or agent.
Run commands inside an existing sandbox with exec <session-id> -- <command...>.
Inspect session state with list and status.
Remove sessions with destroy when they are no longer needed.

Safe defaults

Prefer --network off unless the task explicitly needs downloads or live network access.
Prefer narrow package sets over broad sandboxes.
Prefer machine-readable output when the result feeds another step.
Use list before destroy if you need to confirm the active session set.
For automation, capture sessionId from create --json output and reuse it for exec, status, and destroy.

Input and output expectations

Prefer plain-text nixo commands for human guidance and shell examples.
Prefer --json for agent-to-agent handoff, scripts, or any step that will parse command output.
Treat create --json as the canonical machine-readable entrypoint because it returns the sessionId needed for later steps.
Keep JSON consumers on nixo catalog --json unless they explicitly need grouped categories, then use nixo catalog --json --grouped.
Emit nixosandbox only as a compatibility fallback when nixo is unavailable or the user asks for the legacy name.

Common failure patterns

Could not find flake.nix:
- set NIXOSANDBOX_FLAKE_ROOT to a directory containing flake.nix, or run from the repo root.
create option conflicts:
- never combine --with, --profile, and --spec in the same command.
Invalid package names with --with:
- confirm package names through catalog first.

When to read more

nixo CLI

Use this skill for runtime-agnostic workflows around the nixo command line.

When not to use

Do not use this skill for Nix flake authoring or package derivation work unless the task explicitly centers on the nixo CLI workflow.

Do not use this skill when the user only needs raw nix build, nix develop, or bubblewrap commands outside a sandbox session flow.

Do not use this skill when another repo-local workflow overrides the CLI, such as project-specific wrapper scripts or extension-only APIs.

Naming

Use nixo as the default command in all new instructions, prompts, and automation.

Use nixosandbox only when the user explicitly asks for the legacy name or when nixo is unavailable.

Keep flags and behavior identical across both names.

Core workflow

Discover available packages with catalog.

Create a sandbox with create, using --with for package lists or --profile for named presets.

Use --json when the output will be parsed by another tool or agent.

Run commands inside an existing sandbox with exec <session-id> -- <command...>.

Inspect session state with list and status.

Remove sessions with destroy when they are no longer needed.

Safe defaults

Prefer --network off unless the task explicitly needs downloads or live network access.

Prefer narrow package sets over broad sandboxes.

Prefer machine-readable output when the result feeds another step.

Use list before destroy if you need to confirm the active session set.

For automation, capture sessionId from create --json output and reuse it for exec, status, and destroy.

Input and output expectations

Prefer plain-text nixo commands for human guidance and shell examples.

Prefer --json for agent-to-agent handoff, scripts, or any step that will parse command output.

Treat create --json as the canonical machine-readable entrypoint because it returns the sessionId needed for later steps.

Keep JSON consumers on nixo catalog --json unless they explicitly need grouped categories, then use nixo catalog --json --grouped.

Emit nixosandbox only as a compatibility fallback when nixo is unavailable or the user asks for the legacy name.

Common failure patterns

Could not find flake.nix:

set NIXOSANDBOX_FLAKE_ROOT to a directory containing flake.nix, or run from the repo root.

create option conflicts:

never combine --with, --profile, and --spec in the same command.

Invalid package names with --with:

confirm package names through catalog first.

When to read more

nixo-cli

nixo CLI

When not to use

Naming

Core workflow

Safe defaults

Input and output expectations

Common failure patterns

When to read more

nixo CLI

When not to use

Naming

Core workflow

Safe defaults

Input and output expectations

Common failure patterns

When to read more