Skip to content

README.md

Latest commit

 

History

History
73 lines (50 loc) · 2.67 KB

README.md

File metadata and controls

73 lines (50 loc) · 2.67 KB
Raw

@microsoft/shell-use

A Node client for the shell-use terminal daemon.

The shell-use binary must be on your PATH (or point to it with the SHELL_USE_BIN environment variable or the binary option). The client talks to the per-session daemon directly over its local socket (a named pipe on Windows, a Unix socket elsewhere) and starts the daemon automatically.

Install

npm install @microsoft/shell-use # Node 20+

bun add @microsoft/shell-use # Bun

deno add npm:@microsoft/shell-use # Deno 2

The package is only ESM

Runtime Requirements

  • Node: 20+
  • Deno: 2
  • Bun: *

Note: On Windows, Deno requires all permissions (-A / --allow-all) instead of just --allow-read --allow-write due to the use of named pipes for IPC with the daemon.

Quick start

import { ShellUse } from "@microsoft/shell-use";

const su = new ShellUse();
await su.open();
await su.submit("echo hello");
await su.waitCommand();
await su.expectText("hello");
await su.expectExitCode(0);
await su.close();

Errors

Every failure maps to one of the daemon's exit codes:

Class exitCode Meaning
ExpectationError 1 an expect/wait condition was not met
UsageError 2 invalid argument (e.g. a bad regex)
NoSessionError 3 no active session
DaemonError 4 daemon could not be reached or started
VersionMismatchError 4 the daemon's version differs from this package
InternalError 5 internal daemon error

All derive from ShellUseError and carry kind and exitCode. waitX and expectX reject with ExpectationError on failure.

On its first call, a client checks that the running daemon's version matches the package version and throws VersionMismatchError if they differ. Stop the daemon (daemonStop) so it restarts with the current binary, or point SHELL_USE_BIN at a matching one.

API

new ShellUse(session?, { binary?, home? }) mirrors the CLI: open / run, type / write, submit, press / keys, mouse.click|move|down|up|drag|scroll, resize, signal / kill, state, text, cells, get (+ getCommand / getOutput / getExitCode / getCwd / getCursor / getSize), screenshot, waitText / waitIdle / waitCommand / waitExit, expectText / expectExitCode / expectOutput / expectSnapshot, and close.

Module-level helpers: sessions(), closeAll(), daemonStatus(), daemonStop(), getRecording().

Configuration

Variable Purpose
SHELL_USE_BIN path to the shell-use binary
SHELL_USE_SESSION default session name
SHELL_USE_HOME daemon state directory (sockets, pids)