Install

Install the Grain desktop app and its bundled CLI on macOS, Windows or Linux, run grain setup to sign in and connect your agent, and wire a project.

Grain is a desktop app for macOS, Windows and Linux with a grain CLI inside it. Install the app, put grain on your PATH, then run grain setup to sign in and connect Claude Code or Codex.

Connecting from Claude, ChatGPT or another AI tool, or from a computer without the app? Use the hosted server instead. See Connect your AI tool; it needs no app or CLI.

1. Install the app and CLI

One command installs the app and links the grain command:

# macOS or Linux
curl -fsSL https://rungrain.com/install.sh | sh

# Windows (PowerShell)
irm https://rungrain.com/install.ps1 | iex

What each installer does:

System	App	`grain` command
macOS	`Grain.app` in `/Applications`, or `~/Applications` when `/Applications` is not writable	`~/.local/bin/grain` links to the CLI inside `Grain.app`
Windows	Per-user installer in `%LOCALAPPDATA%\Programs\grain`, no admin rights	`%USERPROFILE%\.local\bin\grain.cmd`, added to your user `PATH`
Linux	The self-updating AppImage in `~/Applications`, no `sudo`. `GRAIN_INSTALL_FORMAT=deb` installs the `.deb` instead (asks for `sudo`)	`~/.local/bin/grain`

The installers pick your CPU (Apple Silicon, Intel, x64 or Arm), check the download against the release's published SHA-256 checksums, and install for your user only. Run the same command again to update: it quits Grain, installs the new version and reopens it.

On macOS you can use Homebrew instead: brew install --cask greenfield-inc/tap/grain.

You can also download the app yourself. The link picks your system; /api/download/mac, /api/download/windows and /api/download/linux (add ?format=deb for the Debian package) choose one. Then open the app, go to Settings → Integrations, and run the Grain CLI commands it shows in a terminal.

Windows builds are not yet code-signed, so SmartScreen may warn on a downloaded installer. Choose More info, then Run anyway. The PowerShell installer avoids the prompt.

Check that your shell finds the command:

command -v grain
grain --version

If command -v prints nothing, open a new terminal, or add the folder for the current shell:

export PATH="$HOME/.local/bin:$PATH"

The app refreshes its bundled CLI when it updates. There is no separately published npm package or standalone public CLI release; unrelated npm packages named grain are not Grain.

The one-command path is:

grain setup

It signs you in through your browser if needed, installs the Grain plugin into Claude Code or Codex (whichever it finds), checks that the MCP server starts, and opens Grain. Pass --claude or --codex to choose clients, --no-open to skip opening the app, or --check to only report readiness. Integrations covers the plugin commands it runs.

To sign in on its own, run:

grain login
grain status

grain login opens your browser to sign in to Grain, or to create an account (grain login --signup). When you finish, the terminal saves revocable CLI authentication in your system's secure store: the macOS Keychain, Windows' per-user encryption (DPAPI), or the Linux Secret Service keyring (GNOME Keyring or KWallet, through secret-tool). On Linux without a keyring, such as a headless server, use the hosted server in Connect your AI tool. Do not copy its token into a project, shell script, MCP config or issue. grain status should report a logged-in state. To remove local credentials later, run grain logout.

If login fails, check that your browser finished on the success page and that the terminal is still waiting, then retry. Do not try to repair CLI authentication by opening a private workspace URL or by putting a token in the MCP server configuration.

3. Link a project

From a project folder:

grain init --template html --name "First artifact"
grain doctor

grain init creates or links a workspace, and writes recognized project agent configuration. If no recognized config exists, it creates .mcp.json; existing .mcp.json, .codex/config.toml and .cursor/mcp.json are updated while unrelated servers are preserved. It also manages GRAIN.md and a pointer in an existing AGENTS.md or CLAUDE.md. It never creates those user instruction files from scratch.

Use these safe options when you are not ready to write files:

grain init --dry-run
grain init --no-agent-config

--dry-run validates and reports the planned operation without creating a workspace, uploading, opening the app, changing defaults or writing files. --no-agent-config still creates/links the workspace but skips repository agent wiring. The complete configuration examples are on Integrations.

grain doctor checks local authentication and workspace-link state. Pass a path to inspect another folder:

grain doctor path/to/project

4. Confirm the first path

The smallest useful verification is:

grain status
grain doctor
grain --help

You are ready when status shows a logged-in account and a linked workspace, doctor reports no link/auth failure, and help prints the current command families. Continue with First artifact to create a complete page and obtain a private workspace URL before choosing whether to share it.

Supported client boundary

The desktop app and CLI run on macOS, Windows and Linux. Native Claude Code and Codex plugins ship with the app; Cursor and other compatible clients use the project stdio configuration written by grain init. See Integrations for exact client setup. From Claude or ChatGPT, or a computer without the app, use the hosted server in Connect your AI tool.