Bash Tool

The Bash tool lets Nilux AI execute shell commands directly in your project environment. It runs commands in a persistent shell session with built-in safety features: timeout enforcement, sandbox restrictions, and optional background execution.

Parameters

Parameter	Type	Required	Description
`command`	string	Yes	The shell command to execute
`timeout`	number	Yes	Maximum execution time in milliseconds
`description`	string	No	A 5-10 word description of what the command does
`run_in_background`	boolean	No	Run the command in the background and return immediately
`dangerouslyOverrideSandbox`	boolean	No	Override default restrictions (use with caution)

Usage Examples

Basic Command

The agent runs a simple directory listing:

> What files are in the src directory?

Agent invokes Bash:
  command: ls src/
  timeout: 5000
  description: List files in src directory

Result:
  components/
  lib/
  app/
  index.ts

Running Tests

> Run the test suite for the auth module

Agent invokes Bash:
  command: npm test -- --testPathPattern=auth
  timeout: 60000
  description: Run auth module tests

Result:
  PASS  src/__tests__/auth.test.ts
    login flow
      ✓ returns tokens on valid credentials
      ✓ rejects invalid password
      ✓ handles expired tokens
  Tests: 3 passed, 3 total

Installing Dependencies

> Install the project dependencies

Agent invokes Bash:
  command: npm install
  timeout: 120000
  description: Install package dependencies

Background Execution

For long-running commands, the agent can use run_in_background: true. This returns immediately with a shell ID, and the agent can check output later.

> Start the dev server

Agent invokes Bash:
  command: npm run dev
  timeout: 300000
  run_in_background: true
  description: Start development server

Result:
  Shell started (id: shell-abc123)
  Server running at http://localhost:3000

Tip: Background execution is useful for dev servers, database migrations, and build processes that take more than a few seconds.

Directory Verification

Before creating files or directories, the agent should verify the parent path exists:

Check parent: ls src/components — confirm the directory exists
Then create: mkdir src/components/NewFeature — create within confirmed location

This prevents commands from failing due to missing parent directories.

Path Quoting

Commands with spaces in file paths must be quoted:

# Correct
cd "/Users/name/My Documents"
python "/path/with spaces/script.py"

# Incorrect — will fail
cd /Users/name/My Documents
python /path/with spaces/script.py

The agent is instructed to always quote paths containing spaces.

Safety

By default, commands run with built-in safety restrictions to prevent accidental damage to your system.

Warning: Only use dangerouslyOverrideSandbox: true for commands that legitimately need elevated access.

Timeout Guidelines

Set timeouts based on expected command duration. Short commands (file listings, git status) need a few seconds. Builds and installs may need a few minutes. For long-running processes (dev servers), use run_in_background.

Output Handling

Very long command outputs are automatically truncated to keep the agent's context focused. If the full output is needed, the agent can redirect output to a file and read it with the Read tool.

Common Patterns

Check before create:

ls foo        # Verify directory exists
mkdir foo/bar # Create within confirmed directory

Run formatted:

npx prettier --write src/components/Header.tsx

Git operations:

git diff --stat
git log --oneline -10

Build verification:

npx tsc --noEmit

Next Steps

Read — Reading file contents
Edit — Targeted file modifications
Glob — Finding files by name
Tools Overview — All available tools