# The grasp command > Use Graspable from a terminal or a script. Create projects, start runs, follow them, check and preview. Source: https://graspable.dev/docs/cli `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** ```bash curl -fsSL https://graspable.dev/grasp/install.sh | sh ``` **Windows** ```powershell powershell -ExecutionPolicy ByPass -c "irm https://graspable.dev/grasp/install.ps1 | iex" ``` **Homebrew (macOS)** ```bash 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`. ## Sign in `grasp` needs an AI to work with. Sign in once: ```bash 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: ```bash 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 `. 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 ```bash 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, which means the project builds and loads in a browser. 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](#approvals) below. ## Update Run the install line again. It installs the newest version and removes the old one. ```bash curl -fsSL https://graspable.dev/grasp/install.sh | sh ``` With Homebrew: ```bash 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 [--template ]` | Create a project. `grasp templates` lists the templates | | `grasp files `, `grasp cat ` | Look at a project's files | | `grasp run ""` | Ask the agent to build or change something | | `grasp runs ` | Earlier runs | | `grasp logs [--follow]` | What a run did | | `grasp approve yes\|no` | Answer an approval request | | `grasp cancel ` | Stop a run | | `grasp check ` | Build the project and load it in a headless browser | | `grasp preview ` | Start the live preview and print its address | | `grasp plugins`, `grasp skills` | Manage [plugins](https://graspable.dev/docs/plugins.md) and [skills](https://graspable.dev/docs/skills.md) | | `grasp mcp` | The [Graspable MCP server](https://graspable.dev/docs/mcp-server.md) | | `grasp token create [--scope read\|run\|admin]` | An access token for the [API](https://graspable.dev/docs/api.md) | | `grasp serve [--port ]` | 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 ` | The model. Optional for `claude-code` and `codex` | | `--provider ` | 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](https://graspable.dev/docs/approvals-and-safety.md). ## Long-running and background work ```bash 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`.