Documentation
CLI Reference

CLI Reference

Complete command-line interface reference for Shai.

Commands

shai

Main command - starts a sandbox in the current directory.

1shai [flags] [-- command [args...]]

shai generate

Generate a default .shai/config.yaml file.

1shai generate

Creates .shai/config.yaml with sensible defaults.

shai version

Display version information.

1shai version

Flags

--read-write, -rw <path>

Repeatable: Yes

Mark a path as writable. Path must exist.

1shai -rw src/components
2shai -rw src -rw tests

--resource-set, -rs <name>

Repeatable: Yes

Opt into additional resource sets beyond config’s apply rules.

1shai -rw src --resource-set gpu-access
2shai -rs tools-1 -rs tools-2

--image, -i <image>

Override the container image.

1shai --image ghcr.io/my-org/custom:latest

Takes precedence over config file and apply rules.

--user, -u <user>

Override the target container user.

1shai --user developer

Default: shai

--privileged

Run the container in privileged mode.

1shai --privileged
Reduces container isolation. Use with caution.

--var, -v KEY=value

Repeatable: Yes

Provide template variables for config.

1shai --var TAG=v1.2.3 --var ENV=staging

Used with ${{ vars.KEY }} in config.

--verbose, -V

Dump bootstrap details and resource decisions.

1shai --verbose

Shows:

  • Bootstrap script
  • Resolved resource sets
  • Network filtering rules
  • Mount points

--no-tty, -T

Disable TTY allocation.

1shai --no-tty -- npm test

Useful for structured log output and CI/CD.

--config <path>

Override config file location.

1shai --config /path/to/custom-config.yaml

Default: .shai/config.yaml in workspace root

--help, -h

Show help message.

1shai --help

Post-Setup Command

Everything after -- is executed inside the sandbox after setup:

1shai -rw src -- npm test
2shai -rw backend -- go build ./...
3shai -rw . -- bash -c "echo hello && pwd"

Without --, Shai drops you into an interactive shell.

Examples

Basic Usage 

 1# Interactive shell (read-only)
 2shai
 3
 4# Interactive shell (src writable)
 5shai -rw src
 6
 7# Run command
 8shai -- npm test
 9
10# Run command with write access
11shai -rw src -- npm run build

Multiple Paths 

1# Multiple writable paths
2shai -rw src/auth -rw src/payments -rw tests
3
4# Run tests with write access to coverage output
5shai -rw coverage -- npm test

Resource Sets 

1# Add resource sets
2shai -rw ml --resource-set gpu-access --resource-set wandb-api
3
4# Override image
5shai -rw src --image ghcr.io/my-org/dev:latest
6
7# Custom user
8shai -rw backend --user developer

Template Variables 

1# Provide template vars
2shai --var ENV=production --var REGION=us-west-2 -rw infrastructure
3
4# Multiple vars
5shai --var TAG=v2.0.0 --var DEBUG=true

Debugging 

1# Verbose output
2shai -rw src --verbose
3
4# Inspect bootstrap without running
5shai -rw src --verbose -- /bin/true
6
7# No TTY for logs
8shai --no-tty -- ./run-tests.sh > test.log

Complex Commands 

1# Chain commands
2shai -- bash -c "npm install && npm test"
3
4# With environment
5shai -- env NODE_ENV=test npm test
6
7# Multiple commands
8shai -- sh -c "echo start && npm run build && echo done"

Exit Codes

CodeMeaning
0Success
1General error
2Docker not available
3Config invalid
4Path doesn’t exist
125Docker daemon error
126Command cannot execute
127Command not found
130Terminated by Ctrl+C

Environment Variables

DOCKER_HOST

Override Docker daemon location.

1export DOCKER_HOST=unix:///var/run/docker.sock
2shai

SHAI_CONFIG

Default config file location.

1export SHAI_CONFIG=/path/to/config.yaml
2shai

Shell Completion

Bash 

1shai completion bash > /etc/bash_completion.d/shai

Zsh 

1shai completion zsh > ~/.zsh/completions/_shai

Fish 

1shai completion fish > ~/.config/fish/completions/shai.fish

Tips

Quick Iteration 

1# Use short flags
2shai -rw src -V -- npm test
3
4# Omit redundant flags
5shai -rw .  # Entire workspace writable

Combining Flags 

1# All flags together
2shai \
3  --image custom:latest \
4  --user dev \
5  --resource-set tools \
6  --var TAG=v1.0.0 \
7  --verbose \
8  -rw src \
9  -- npm run build

Default Behavior 

1# No command = interactive shell
2shai -rw src
3
4# No -rw = read-only workspace
5shai
6
7# No config = uses embedded defaults
8shai  # Works even without .shai/config.yaml

See Also