The grasp command · Graspable

Use Graspable from a terminal or a script. Create projects, start runs, follow them, check and preview.

grasp is Graspable as a command. It does what the app does: create projects, ask the agent to build, follow the run, check the result and start the preview.

Install it

macOS and Linux

curl -fsSL https://graspable.dev/grasp/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://graspable.dev/grasp/install.ps1 | iex"

Homebrew (macOS)

brew install --cask graspable-dev/tap/grasp

The installer downloads the build for your computer, checks it against its published checksum and puts the grasp command in ~/.local/bin (on Windows, in a folder it adds to your PATH). Nothing else needs installing: grasp brings what it needs to install packages, build and run a preview.

If your terminal says grasp: command not found, the installer's last lines show the one line that adds ~/.local/bin to your PATH. Run it and open a new terminal.

Do you already have the Graspable app? Then you can also install the command from Settings → Plugins and connectors → Use Graspable from other tools. Both ways give the same grasp.

grasp needs an AI to work with. Sign in once:

grasp login

It asks what should power the agent and signs you in:

Choice	What it uses	Also directly
ChatGPT subscription	The Graspable agent, signed in with ChatGPT in your browser	`grasp login chatgpt`
Claude subscription	Claude Code on this computer, with its own sign-in	`grasp login claude`
ChatGPT through Codex	The Codex CLI on this computer, with its own sign-in	`grasp login codex`
An API key	The Graspable agent with a key from Anthropic, OpenAI, OpenRouter and others	`grasp login key anthropic`

An API key is typed once and kept in your computer's keychain (on Linux, in the Secret Service). On a computer without one, set the key in the environment variable GRASPABLE_API_KEY instead.

Check what is set up at any time:

grasp whoami

Change the default later with grasp use, for example grasp use codex or grasp use pi --provider openrouter --model anthropic/claude-sonnet-4.5.

Shared with the Graspable app

grasp and the app use the same set-up on one computer:

Projects, runs, memory, plugins and skills are the same in both.
The default AI and model are shared. Change it in the app's Settings or with grasp use, and the other follows.
Sign-ins with a subscription are shared: a ChatGPT sign-in made in the app works in grasp and the other way round, and Claude Code and Codex keep their own sign-in, which both use.
API keys are not shared. The app keeps its keys in its own keychain entry, which grasp cannot read. If the app's default is an API key account, add that key once with grasp login key <provider>.

When the app is open, grasp talks to it, so a run you start in the terminal appears in the app as it happens. When it is closed, grasp starts the same agent in the background. On a computer without a screen, you can also start it yourself with grasp serve.

Your first run

grasp new "Solar system"
# 3f9a12bc  created (react-xr-developer); packages are installing

grasp run 3f9a12bc "Hang a small solar system in the middle of the room. The planets orbit at different speeds."

grasp preview 3f9a12bc
# http://127.0.0.1:51234

grasp new creates a project and prints its id.
grasp run sends your request. It prints what the agent does and returns when the run is finished. The exit code is 0 when the run completed, which means the project builds and loads in a browser.
grasp preview starts the live preview. Open the address in a browser.

When the agent wants to run a command or reach outside the project, grasp run asks you first. See Approvals below.

Update

Run the install line again. It installs the newest version and removes the old one.

curl -fsSL https://graspable.dev/grasp/install.sh | sh

With Homebrew:

brew upgrade --cask grasp

grasp version prints the installed version.

Uninstall

Delete ~/.local/bin/grasp and the folder ~/.graspable/cli. With Homebrew: brew uninstall --cask grasp. Your projects and settings stay where they are.

Commands

Command	What it does
`grasp login`, `grasp whoami`, `grasp use`, `grasp logout`	Sign in and choose the default AI
`grasp projects`	List projects
`grasp new <name> [--template <id>]`	Create a project. `grasp templates` lists the templates
`grasp files <project>`, `grasp cat <project> <path>`	Look at a project's files
`grasp run <project> "<request>"`	Ask the agent to build or change something
`grasp runs <project>`	Earlier runs
`grasp logs <run> [--follow]`	What a run did
`grasp approve <run> <id> yes\|no`	Answer an approval request
`grasp cancel <run>`	Stop a run
`grasp check <project>`	Build the project and load it in a headless browser
`grasp preview <project>`	Start the live preview and print its address
`grasp plugins`, `grasp skills`	Manage plugins and skills
`grasp mcp`	The Graspable MCP server
`grasp token create <name> [--scope read\|run\|admin]`	An access token for the API
`grasp serve [--port <n>]`	Run the agent without the app
`grasp status`	Is the agent running?

Add --json to projects, runs, logs and run for output a program can read. With --json, grasp run prints one event per line.

Options of grasp run

Option	Meaning
`--engine claude-code\|codex\|pi`	What powers this run. Default: what you set up with `grasp login`
`--model <id>`	The model. Optional for `claude-code` and `codex`
`--provider <id>`	For `pi`: the provider, for example `anthropic`, `openai` or `openrouter`
`--policy auto\|guarded\|strict`	What the agent asks first. Default: `guarded`
`--approve yes\|no`	Answer every approval request the same way
`--no-wait`	Print the run id and return at once

claude-code and codex use the sign-in of those tools on your computer. pi is the Graspable agent, with your ChatGPT sign-in or an API key.

Approvals

With the guarded policy the agent asks before it runs a command or reaches outside the project. In a terminal, grasp run asks you. In a script it waits; answer from another process with grasp approve, or pass --approve yes, or use --policy auto to let the agent work without asking. See Approvals and safety.

Long-running and background work

run=$(grasp run 3f9a12bc "Add hand tracking" --no-wait)
grasp logs "$run" --follow

grasp logs --follow returns when the run is finished, with the same exit code as grasp run.