CLI Reference

All 18 Switchyard CLI commands — process management, launch, ports, groups, config, monorepo support, and integrations.

Process Management

`sy ls`

List all running node processes. Alias: sy list. This is the default command when running sy with no arguments.

`sy kill <target>`

Kill a process by name, PID, or :port.

sy kill myapp       # by label
sy kill 12345       # by PID
sy kill :3000       # by port
sy kill all         # kill everything

`sy clean`

Find and kill orphaned node processes (unknown label, no port). Also cleans stale registry entries.

`sy register <label>`

Label the current directory's running process.

Option	Description
`-p, --pid <pid>`	Specify PID to label
`--port <port>`	Specify port to label

`sy watch`

Live-updating process table. Refreshes every 2 seconds by default.

Option	Description
`-i, --interval <ms>`	Refresh interval in ms (default: 2000)

`sy health`

Health check all registered processes. Shows green/amber/red status per process with memory and port checks.

`sy status`

One-line process summary. Useful for shell prompts or tmux status bars.

# Output: sy: 3 online · 1 degraded · 0 dead

Launch & Lifecycle

`sy run [cmd...]`

Launch a dev server through Switchyard. Smart detection reads packageManager, framework from deps, and workspace scripts from package.json.

Option	Description
`-l, --label <name>`	Custom label
`-p, --port <port>`	Port to use (auto-resolves conflicts)
`-d, --detach`	Run in background with log capture

sy run                        # auto-detect from package.json
sy run web                    # run a specific monorepo workspace
sy run --detach --port 3001   # background on port 3001
sy run -- next dev            # specific command

In a monorepo, sy run <name> first checks for compound scripts (e.g. dev:web in root package.json), then falls back to workspace filter commands (pnpm --filter web run dev). Running from inside an app directory auto-detects that workspace.

`sy info`

Show what Switchyard detected about the current project — package manager, framework, workspaces, ports, compound scripts.

sy info
#   Project      taskjunky
#   Pkg Manager  pnpm
#   Monorepo     yes
#   Workspaces:
#     web (apps/web) next :3000
#     docs (apps/docs) next :3002
#   App Scripts:
#     web → dev:web
#     docs → dev:docs

`sy restart <target>`

Kill and relaunch a registered process. Only works for processes started via sy run (command must be stored in the registry).

`sy logs <target>`

View logs for a detached process. Logs are captured at ~/.switchyard/logs/<label>.log.

Option	Description
`-f, --follow`	Follow log output in real time
`-n, --lines <n>`	Number of lines to show (default: 50)
`--clear`	Clear the log file

Port Management

`sy port next`

Find the next available port starting from 3000.

Option	Description
`-s, --start <port>`	Starting port number (default: 3000)

`sy port reserve <port> <label>`

Reserve a port for a project. Stored in ~/.switchyard/ports.json.

`sy port release <port>`

Free a reserved port.

`sy port list`

List all port reservations.

Process Groups

Bundle related processes for bulk operations.

`sy group create <name>`

Create a named group.

`sy group add <group> <label>`

Add a process label to a group.

`sy group remove <group> <label>`

Remove a process from a group.

`sy group list`

List all groups and their members.

`sy group kill <name>`

Kill all processes in a group.

`sy group restart <name>`

Restart all processes in a group.

sy group create fullstack
sy group add fullstack frontend
sy group add fullstack api
sy group add fullstack worker
sy group restart fullstack   # restart all three

Configuration

`sy init`

Create a .switchyard.json config in the current project directory. Auto-detects defaults from package.json.

Option	Description
`-l, --label <name>`	Project label
`-p, --port <port>`	Preferred port
`-c, --command <cmd>`	Dev command

`sy config get <key>`

Get a global config value.

`sy config set <key> <value>`

Set a global config value. Stored at ~/.switchyard/config.json.

`sy config list`

List all config values with defaults.

Key	Default	Description
`portRangeStart`	3000	Port scan start
`portRangeEnd`	9999	Port scan end
`refreshInterval`	2000	Watch refresh (ms)
`colorMode`	auto	auto, dark, light, none
`defaultDetach`	false	Default to background mode
`logRetentionDays`	7	Days to keep logs

Option	Description
`-s, --shell <shell>`	Shell type: `zsh` or `bash` (default: zsh)