API reference

CLI

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.

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 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
  1. grasp new creates a project and prints its id.
  2. 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. 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.
  3. 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. 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.