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.
Choose how to edit
If a connected coding agent will edit the files itself, it can use Graspable through MCP to create a free web project, read and write files, build, check and preview it. Those operations need no additional AI sign-in and spend no Graspable Credits. The connected agent’s own usage terms still apply. Premium templates and services keep their plan requirements.
The installer links to the connection guide. To ask Graspable’s agent to generate changes with grasp run, configure its AI account first.
Sign in
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
graspand 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
graspcannot read. If the app's default is an API key account, add that key once withgrasp 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 newcreates a project and prints its id.grasp runsends your request. It prints what the agent does and returns when the run is finished. The exit code is 0 when the run completed. Read the check report too: a browser or native runtime check can be skipped when its environment is unavailable. A completed run alone does not prove the scene ran.grasp previewstarts 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. A premium template needs your Graspable session in GRASPABLE_SESSION, so your plan can be checked |
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 history <project> |
The project's versions, newest first: one per run that changed files |
grasp restore <project> <version> |
Put the files back to a version. Recorded as a new version, so nothing is lost |
grasp publish <project> [--title "…"] [--name <name>] [--private] [--no-fork] |
Publish the app at an address of its own. Needs your Graspable session in GRASPABLE_SESSION (the app signs in for you) |
grasp fork <app-id> |
Continue from a public app: a new project with its source and history |
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, history, restore 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.
Usage counts
grasp counts which commands and MCP tools are used, by which agent, and whether they worked: never their arguments or output. See Privacy and telemetry for exactly what is sent. Turn it off with grasp telemetry off (or DO_NOT_TRACK=1); grasp telemetry says whether it is on.
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.