Shell usage

Configure real shell execution, workspace filesystems, analysis, and sandbox clients.

Use this page after the Quickstart.

Choose workspace commands

Pass the commands that just-bash should expose in the workspace-backed runtime.

import { createShellRuntime } from '@vitehub/shell'
import { createJustBashProvider } from '@vitehub/shell/providers/just-bash'

const runtime = createShellRuntime({
  provider: createJustBashProvider({
    commands: ['pwd', 'ls', 'cat', 'head', 'rg'],
    fs,
  }),
})

The runtime accepts real shell syntax. Pipes, redirects, chaining, command substitution, and multiline commands are passed through to the provider.

Use read-only files

import { createReadonlyWorkspaceFs } from '@vitehub/shell/workspace'

const fs = createReadonlyWorkspaceFs(workspace)

Use read-only filesystems for inspection surfaces.

Use writable files

import { createWritableWorkspaceFs } from '@vitehub/shell/workspace'

const fs = createWritableWorkspaceFs(workspace)

Writable filesystems require the workspace to implement writeFile, mkdir, and rm. Keep the exposed command list narrow.

Analyze commands

Use analyzeShellCommand() when you need advisory metadata before execution.

import { analyzeShellCommand } from '@vitehub/shell'

const analysis = await analyzeShellCommand('rg TODO docs | head -n 20')

Run workspace shell commands

Use runWorkspaceInspectionCommand() when AI tools should execute against a ViteHub workspace filesystem.

import {
  createReadonlyWorkspaceFs,
  runWorkspaceInspectionCommand,
  workspaceMountPoint,
} from '@vitehub/shell/workspace'

const result = await runWorkspaceInspectionCommand(workspace, 'rg TODO docs | head -n 20', {
  commands: ['rg', 'head'],
  cwd: workspaceMountPoint,
  fs: createReadonlyWorkspaceFs(workspace),
  maxOutputLength: 30_000,
})

Clean paths

Use path helpers before reading or mutating workspace paths from input.

import {
  cleanWorkspaceMutationPath,
  cleanWorkspaceShellPath,
} from '@vitehub/shell/workspace'

const readPath = cleanWorkspaceShellPath('/workspace/docs/README.md')
const writePath = cleanWorkspaceMutationPath('generated/summary.md')

cleanWorkspaceMutationPath() rejects the workspace root.

Use a Cloudflare shell client

Use cloudflare-shell when a Cloudflare sandbox-compatible client owns execution.

import { createShellRuntime } from '@vitehub/shell'
import { createCloudflareShellProvider } from '@vitehub/shell/providers/cloudflare'

const runtime = createShellRuntime({
  provider: createCloudflareShellProvider({ sandbox }),
})

const result = await runtime.exec('node --version', {
  timeout: 5_000,
})

The client must expose exec(command, args, options) plus supports.execCwd and supports.execEnv.