Spruce CLI

spruce-cli is a command-line tool that ships with Spruce. It's primarily used by the Spruce app itself (to manage the daemon that backs terminal sessions), but it's also useful for scripting and debugging.

The CLI is in active development and the surface is subject to change. Command names, flags, and output formats may move between releases. Treat anything below as current-as-of-writing rather than a stable contract.

The Spruce daemon

The daemon is a background process that handles terminal PTYs, session persistence, and inter-process communication between the Spruce app and running sessions.

Starting / inspecting / stopping

spruce-cli daemon run          # start the daemon (Spruce does this automatically)
spruce-cli daemon status       # show whether the daemon is running and its version
spruce-cli daemon stop         # stop the daemon (Spruce does this on quit)

The daemon listens on a Unix socket on macOS / Linux (~/Library/Application Support/com.spruce.app/daemon.sock) or a named pipe on Windows. It starts automatically when Spruce launches and shuts down when the app quits.

Manual restart

If the daemon gets into a bad state, stopping and restarting is usually enough:

spruce-cli daemon stop
spruce-cli daemon run

Spruce reconnects on the next action that needs the daemon. If a restart doesn't clear a problem, quit and reopen the Spruce app.

Sessions

The CLI is the off-Spruce way to interact with the terminal sessions the daemon manages. Useful when you want to attach to a session from a tmux pane, a remote shell, or a script — anywhere outside the Spruce app.

spruce-cli session list                  # list every running session, with artifact + working dir
spruce-cli session attach <id>           # attach the current shell to a running session's PTY
spruce-cli session kill <id>             # kill a running session
spruce-cli session open-in-terminal <id> # open a new window in your native terminal app, attached

session attach connects your current shell directly to the daemon-held PTY. Detaching (Ctrl-Q in most cases) exits without killing the session; everything keeps running for the next attach. This is the one you want when you're in a shell and want the session here.

session open-in-terminal is different: it spawns a new tab or window in a terminal app (running spruce-cli session attach <id> inside it), or refocuses an existing tab that's already attached to that session. It's mainly used by:

• The Spruce desktop app. When you click Open in native terminal on a session, the app shells out to this command.
• Scripts / automation. When you want to programmatically pop a session into its own window without the script process holding the attach.

The launcher it picks is, in order: the explicit --app flag, the parent terminal it was invoked from (auto-detected via $TERM_PROGRAM), then your configured Native terminal app (see Shell Configuration), then the OS default. So running it directly from a shell usually does what you'd expect: opens a tab in the same terminal you're already in. But if you're already in a shell, plain session attach is simpler.

<id> accepts partial IDs; Spruce resolves the unique prefix. If multiple sessions match, Spruce shows an interactive picker.

Other commands

spruce-cli exposes additional commands for scripting and debugging. Run spruce-cli --help for the full list.

Common ones:

• spruce-cli project list: list projects known to your installation.
• spruce-cli project open <id>: open a project in the Spruce app.
• spruce-cli artifact ls <project>: list artifacts in a project.

Scripting hooks

Because spruce-cli exits with meaningful status codes and emits structured output (--output json), you can compose Spruce operations with other scripts. Example: a shell function that creates a feature and prints its ID:

new-feature() {
  local title="$1"
  spruce-cli artifact create feature "$title" --output json | jq -r .id
}

The available subcommands today are daemon, project list / open, and artifact create / get / search / body-edit / update / delete. spruce-cli --help and spruce-cli artifact --help enumerate the current set.

Install location

spruce-cli ships alongside the Spruce app binary. The easiest way to put it on PATH is from inside the Spruce app: open the command palette (⌘K / Ctrl+K) and run Install Spruce CLI in path. Spruce symlinks the binary into a system-PATH location for you.

If you'd rather wire it up by hand, see Platform Notes for where the binary lives on each platform.

Related

• Sessions — the sessions backed by the daemon.
• Install Spruce — the daemon first launches during Spruce install.
• Platform Notes — platform-specific CLI behaviour.