@tpmjs/sprites-exec

Execute a command inside a sprite and return the output.

Installation

npm install @tpmjs/sprites-exec

Requirements

• SPRITES_TOKEN environment variable - Get your token from https://sprites.dev

Usage

import { spritesExecTool } from '@tpmjs/sprites-exec';

// Run a simple command
const result = await spritesExecTool.execute({
  name: 'my-sandbox',
  cmd: 'ls -la /home'
});

console.log(result);
// {
//   exitCode: 0,
//   stdout: 'total 4\ndrwxr-xr-x 2 root root 4096 Jan 15 10:30 .\n...',
//   stderr: '',
//   duration: 45
// }

// Run with stdin input
const pythonResult = await spritesExecTool.execute({
  name: 'my-sandbox',
  cmd: 'python3',
  stdin: 'print("Hello from stdin!")'
});

// For shell features (pipes, redirects, etc), use bash -c
const shellResult = await spritesExecTool.execute({
  name: 'my-sandbox',
  cmd: 'bash -c "echo hello > /tmp/test.txt && cat /tmp/test.txt"'
});

Shell Commands

Commands are executed directly (like exec.Command in Go), not through a shell. This means shell operators like |, >, >>, && won't work directly.

For shell features, wrap your command with bash -c:

// Won't work: cmd: 'echo hello > file.txt'
// Use instead:
cmd: 'bash -c "echo hello > file.txt"'

Input Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Name of the sprite to execute command in | | cmd | string | Yes | Command to execute (e.g., 'ls -la', 'python script.py') | | stdin | string | No | Optional stdin input to pass to the command | | timeoutMs | number | No | Execution timeout in milliseconds (default: 60000) |

Output

| Field | Type | Description | |-------|------|-------------| | exitCode | number | Command exit code (0 = success) | | stdout | string | Standard output from the command | | stderr | string | Standard error from the command | | duration | number | Execution duration in milliseconds |

Error Handling

The tool throws errors in these cases:

• SPRITES_TOKEN environment variable is not set
• Sprite not found (HTTP 404)
• Command execution timeout
• Invalid or expired API token (HTTP 401)
• Network errors with descriptive messages

License

MIT