Install Graphide

Graphide runs on Linux on x86_64, with a Vulkan driver, and on macOS on Apple silicon. Windows, Intel Macs and Linux on ARM are not supported yet.

You install it in three steps. None of them needs root.

1. Install gr

curl -fsSL https://graphide.com/install.sh | sh

This installs the gr command line tool, about 60 MB, into Graphide’s data folder and links it as ~/.local/bin/gr. The installer checks the download’s SHA-256 before it unpacks anything. It needs curl, awk, tar, mktemp, and sha256sum or shasum, which most systems already have. On Linux it needs glibc: musl systems such as Alpine are not supported.

If ~/.local/bin is not on your PATH, the installer adds it in your shell’s startup file (~/.zshrc, ~/.bashrc, ~/.bash_profile or fish’s conf.d), between the lines # >>> graphide gr >>> and # <<< graphide gr <<<. Open a new terminal for it to take effect, or use the full path to gr that the installer prints on its last line.

2. Sign in

gr login

Your browser opens on Graphide’s sign-in page. Sign in with a provider, or create an account with your email. gr login waits until you are done.

On a machine with no browser, such as an ssh session, gr login notices and prints an address and a code instead. Open the address on any computer, type the code and sign in there. gr login --no-browser asks for this on purpose.

3. Install the app

gr app install

This downloads the Graphide app, about 80 MB, checks it, and installs it:

• macOS: in Applications, as Graphide.
• Linux: in Graphide’s data folder, with a graphide command in ~/.local/bin and an entry in your applications menu.

Then open it on a project:

cd ~/code/my-project
gr app open .

You can also start it from your applications menu, or with graphide on Linux. The first time it opens a project it builds that project’s map; see Map your first project.

What the Linux installer checks

On Linux, gr app install warns about anything the app will miss:

Warning	What to do
No Vulkan driver (libvulkan.so.1)	Install your GPU’s Vulkan driver. On Ubuntu that is mesa-vulkan-drivers. Without it the window cannot draw.
bwrap is missing	Install bubblewrap with your package manager. Agents and plugins run sandboxed with it.
git is missing	Install git. Graphide needs it for projects.
~/.local/bin is not on PATH	Add it, or start the app from the applications menu.

When the install fails

gr app install --json prints one JSON object with ok, and an error.code when ok is false:

Code	Meaning
not_signed_in	Run gr login, then install again.
account_not_active	Your account is waiting to be activated. Your dashboard says where it stands.
no_native_build	No build of the app is published for this machine yet.
unsupported_platform	This machine is not one Graphide runs on.
checksum_mismatch, signature_invalid	The download was damaged or did not verify. Run the command once more, and tell us if it fails again.
download_failed, api_unreachable	Graphide’s servers could not be reached. Check your connection and try again.
app_running	Quit Graphide first, or use gr app update.
busy	Another install or update is running.

Updates

Graphide tells you when an update is out and installs it for you: the app shows an Update button, and the update goes in when Graphide restarts.

From a terminal:

Command	Does
gr version	Prints this build of gr, the daemon’s, and whether a newer one exists.
gr app status	Says which version is installed and whether a newer one is out.
gr app update	Downloads the newest version and stages it for the next restart. --apply puts it in now; quit Graphide first.
gr app rollback	Goes back to the version before the last update.

Where Graphide keeps things

	Linux	macOS
Settings (config.toml)	~/.config/graphide/	~/Library/Application Support/Graphide/
Programs, records, saved chats	~/.local/share/graphide/ and ~/.local/state/graphide/	~/Library/Application Support/dev.graphide.app/
Cache	~/.cache/graphide/	~/Library/Caches/graphide/
A project’s map	.graphide/ inside the project	.graphide/ inside the project

On Linux the folders follow XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME and XDG_CACHE_HOME when you set them. Your sign-in is kept in the system keychain, not in these files.

Uninstall

gr uninstall --dry-run   # see what would go
gr uninstall

gr uninstall removes Graphide’s settings, your saved sign-in, the daemon’s records, and the installed builds and saved chats in Graphide’s data folder. It asks first; -y skips the question. It never touches the .graphide/ folders inside your projects; delete those yourself if you want them gone.

Then remove what is left outside those folders:

• macOS: drag Graphide from Applications to the Bin.
• Linux: remove ~/.local/bin/gr, ~/.local/bin/graphide and ~/.local/share/applications/graphide.desktop.
• Remove the # >>> graphide gr >>> block from your shell’s startup file.

If you connected a terminal agent with gr harness install, run gr harness uninstall <agent> --all before gr uninstall to take Graphide’s part out of those projects’ files.

Removing Graphide from your computer does not delete what Graphide keeps on its servers. Your code and data says how to delete that.