Agent CLI

The crispy CLI lets AI agents control CrispyVibe from inside terminals. Agents can open files, manage terminals, interact with the Shelf, and automate browser previews — all programmatically.

Environment discovery

Every terminal launched inside CrispyVibe has these environment variables set automatically:

Variable	Purpose
`CRISPY_SOCKET`	Unix socket path for IPC
`CRISPY_CONTEXT`	Current context identifier
`CRISPY_VIBESPACE`	Active VibeSpace ID
`CRISPY_PROJECT_PATH`	Root path of the current project

The app’s Resources/bin directory is added to PATH automatically, making the crispy command available without additional setup.

Check if running inside CrispyVibe

test -n "$CRISPY_SOCKET"

Commands

ping

Verify connectivity to the IDE.

crispy ping

identify

Return information about the current context, VibeSpace, and project.

crispy identify

terminal

Manage terminals programmatically.

crispy terminal create          # Create a new terminal
crispy terminal send <id> <text> # Send input to a terminal
crispy terminal wait <id>       # Wait for a terminal to become idle
crispy terminal read <id>       # Read terminal output
crispy terminal list            # List all terminals
crispy terminal close <id>      # Close a terminal

file

Open files in the content viewer.

crispy file open <path>

shelf

Manage Shelf entries.

crispy shelf add <path>    # Pin a file to the Shelf
crispy shelf list           # List all Shelf entries
crispy shelf remove <path> # Remove a file from the Shelf

browser

Control the built-in browser with Playwright-style automation.

crispy browser open <url>              # Open a URL in a new panel
crispy browser list                    # List open browser panels
crispy browser close <id>              # Close a browser panel
crispy browser wait --load_state <s>   # Wait for page load state
crispy browser snapshot --interactive  # Get numbered element tree
crispy browser click --ref <n>         # Click element by ref number
crispy browser type --ref <n> --text <t> # Type into element by ref
crispy browser fill --ref <n> --text <t> # Fill a form field
crispy browser eval <script>           # Evaluate JavaScript
crispy browser screenshot              # Capture visible viewport
crispy browser screenshot --full-page  # Capture entire scrollable page
crispy browser cookies                 # List page cookies
crispy browser storage                 # Read localStorage/sessionStorage

💡 Tip: Use crispy browser snapshot --interactive --json to get a numbered element tree. Reference elements by their --ref number in subsequent click, type, and fill commands.

vibespace

Manage the project lifecycle in the focused VibeSpace.

crispy vibespace add-project <path>      # Add a project folder and focus it
crispy vibespace list-projects           # List active, parked, and unresolved projects
crispy vibespace activate-project <path> # Unpark a parked project and focus it
crispy vibespace park-project <path>     # Park a project (persists state, ends its sessions)
crispy vibespace remove-project <path>   # Remove a project, closing its terminals and browsers

todo

Create and manage Quick Todos and their threads.

crispy todo add --text "<title>"           # Create a todo (optional --body, --project, --color)
crispy todo list --status active           # List todos (optional --project)
crispy todo show <id>                      # Show a todo with its full thread
crispy todo complete <id>                  # also: reopen, update, remove
crispy todo message add <id> --text "<m>"  # Append a message to the todo's thread

Todos default to the terminal’s project (CRISPY_PROJECT_PATH); pass --project <path> to target another, or omit it for a VibeSpace-level todo. Changes appear live in an open Todos surface.

Machine-readable output

All commands accept the --json flag to return structured JSON output suitable for programmatic consumption.

crispy terminal list --json

Context resolution

Commands use the environment variables for implicit context. To target a different terminal or VibeSpace, pass explicit IDs:

crispy terminal read --id <terminal-id>

Explicit IDs override the implicit environment context.

Error codes

When a command fails, it returns one of these error codes:

Code	Meaning
`unknown_method`	Command not recognized
`invalid_params`	Missing or malformed arguments
`terminal_not_found`	Terminal ID does not exist
`vibespace_not_found`	VibeSpace ID does not exist
`file_not_found`	File path does not exist
`permission_denied`	Access outside project boundary
`unsupported_engine`	Terminal engine cannot perform action
`timeout`	Operation exceeded time limit
`not_connected`	No active socket connection
`eval_error`	JavaScript evaluation failed
`stale_ref`	Browser element reference expired
`element_not_found`	Browser selector matched nothing

Security

The CLI socket is owner-only (0600), so only processes running as your user account can connect to it. Any same-user process — including tmux and SSH shells and ACP agents — can use the CLI.
File commands enforce the project root boundary — agents cannot access files outside the project.
Separate CrispyVibe instances use different sockets, preventing cross-instance access.

On remote SSH projects the CLI is relayed over your SSH connection rather than exposed directly. See Remote Agent CLI.

Persistence

Everything created via the CLI (terminals, Shelf entries) persists across app restarts.

Help

Run crispy help to see the full method catalog and usage details.

crispy help