Skip to content

Shell command and Terminal

Jump to bottom
Dang Nguyen edited this page May 20, 2026 · 2 revisions

Steward can run commands or open terminals on your machine from a conversation.

How to use

Type /> to start shell mode, then type your command. Steward chooses transcript or interactive routing from what you run: most shell commands use transcript (streamed stdout/stderr). Supported programs such as vim use an interactive pseudo-terminal (PTY) when the node-pty native bundle is installed—for example />vim.

Transcript mode

  • What you get: stdout/stderr are streamed directly into the conversation as plain text. This is not a full terminal UI (no curses-style TUI).
  • Setup: works on Obsidian desktop with the CLI bridge enabled. You do not need node-pty or the prebuilt native bundle for transcript mode.

Interactive mode

  • What you get: a terminal-style experience (TTY) in the conversation.
  • When it applies: the command starts with a supported interactive program (for example vim, nvim, or supported AI CLIs), and the node-pty native runtime is available.
  • Setup: requires the node-pty native runtime (prebuilt binaries) and a local folder vault so Steward can resolve the bundle path.

Steward runs shell commands

Besides typing /> yourself, Steward's AI can also decide to run a shell command as part of answering your request.

  • You always get to approve first. Before any command runs, Steward shows you what it wants to execute and waits for you to press Run. Nothing happens on your machine until you confirm.
  • Skipping confirmation with a whitelist. If you use a user-defined command and its note includes a cli.whitelist, commands that match a whitelist entry will run without asking. A pattern ending with * matches any command that starts with that prefix (for example echo* matches echo hello). This only applies to regular (non-interactive) commands — interactive terminals always ask for confirmation.
  • Output is kept tidy. After a command finishes, Steward collapses its output into a foldable block so long logs don't clutter your conversation.
  • Interactive terminals. When a command needs a full terminal (for example vim or an AI CLI), Steward will let you know before opening it. Review the message and press Run when you're ready.

What is node-pty, and why is it needed?

microsoft/node-pty is a library that allocates a pseudo-terminal and runs a process attached to it. Many programs (editors, TUIs, REPLs) assume a TTY: they need cursor control, raw input, and window size updates. A normal pipe (transcript mode) cannot provide that.

Steward therefore uses:

  • Transcript mode — regular child processes and pipes (no PTY).
  • Interactive mode — node-pty plus a small companion that bridges the PTY to the Obsidian UI.

The JavaScript part of node-pty ships with the plugin; native .node binaries are platform-specific and must match your OS, CPU architecture, and Node.js ABI (module version). You can either build node-pty from source on your machine (see the microsoft/node-pty build instructions) or install prebuilt native addons instead of compiling.

A widely used source of prebuilts is homebridge/node-pty-prebuilt-multiarch—community-maintained release assets for multiple platforms and Node versions

Easiest path: the plugin writes two installer scripts into your Steward folder in the vault. They download a pinned tarball from that prebuilt-multiarch project and extract it (by default next to the script, under node-pty-prebuilt):

  • install-node-pty-runtime.sh — macOS, Linux, or Git Bash on Windows
  • install-node-pty-runtime.ps1 — Windows PowerShell

Run the one that matches your environment from your vault root. After a successful run, you can use real terminals inside Steward's input and Obsidian's editor.

Built-in interactive programs

These names are listed out of the box: vim, vi, nvim, nano, gemini, claude, qwen, hermes.

Custom interactive programs

In Steward → Settings → CLI, use Interactive programs to list additional executables, separated by commas or new lines (for example htop, btop). Those names are treated like the built-ins for PTY routing.

Related settings

In the same CLI settings section you can also set the shell executable, working directory, and optional node-pty native bundle folder if you did not use the default Steward/node-pty-prebuilt layout.

Clone this wiki locally