# Install Graphide

Graphide is a native app for running and steering coding agents over a live
map of the code. These instructions are for the agent installing it on the
user's machine. Follow them in order; each step prints what the next one
needs.

Supported: Linux on x86_64 (with a Vulkan driver) and macOS on Apple silicon.
Not yet: Windows, Intel Macs, Linux on ARM. On an unsupported machine, say so
and stop.

## Before you run anything, tell the user

"I'll install Graphide in three steps:

1. Install the `gr` command line tool into Graphide's data folder
   (`~/.local/share/graphide` on Linux, `~/Library/Application Support/dev.graphide.app`
   on a Mac; about 60 MB).
2. Sign you in to Graphide. Your browser opens; you sign in or sign up there.
3. Download the Graphide app (about 80 MB) and open it on this project.
   On a Mac it goes in Applications as Graphide; on Linux in
   `~/.local/share/graphide/app`, with a `graphide` command and a menu entry.

The map of your code is processed in Graphide's cloud, and the app asks
before it stores a copy of your code there. Undo everything with
`gr uninstall`, then remove the app as graphide.com/docs/install/#uninstall
says.
Shall I go ahead?"

Wait for the user's go-ahead before running any commands.

## 1. Install the command line tool

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

If it fails, report the error and stop. If `gr` is not on PATH in this shell
yet, use the `gr` the installer names on its last line for every later command:
`~/.local/share/graphide/bin/current/gr` on Linux, and on a Mac
`"$HOME/Library/Application Support/dev.graphide.app/bin/current/gr"`, quoted
for the space.

## 2. Install the app

```sh
gr app install --json
```

If `gr` answers that `app` or `install` is an unknown command, this `gr` comes
from before the app was released: tell the user "Graphide's new app is not
out yet for this installer; the download page at graphide.com/releases has
the current build", and stop.

Otherwise it prints one JSON object. Read:

- `ok`: true means the app is installed. Never claim success when it is false.
- `version`, `path`: what was installed and where.
- `warnings`: tell the user about each one in plain words.
- `error.code` when `ok` is false:
  - `not_signed_in`: sign the user in (below), then run
    `gr app install --json` again.
  - `account_not_active`: the account is waiting for a quick check by the
    Graphide team. Tell the user to open https://graphide.com/dashboard to
    see where it stands; run `gr app install --json` again once it is open.
  - `no_native_build`: no build of the app is published for this machine yet.
    Tell the user and stop.
  - `unsupported_platform`: say which machines are supported and stop.
  - `checksum_mismatch`: the download was damaged. Run the command once more;
    if it fails again, report it and stop.
  - anything else: report `error.message` and stop. Do not retry in a loop.

### Signing in

```sh
gr login
```

It opens the user's browser and waits until they finish, which can take a few
minutes: allow it at least ten minutes, or run it in the background and wait
for it to exit. Tell the user: "Your browser has opened Graphide's sign-in.
Sign in or create an account there; I'll carry on when you're done."

On a machine with no browser (an ssh session), run `gr login --no-browser`
instead. It prints an address and a code: give both to the user to open on
any computer.

Never ask for or type the user's password.

## 3. Open it

From the project the user wants to work on:

```sh
gr app open --json .
```

It starts Graphide on that folder and returns at once. If it refuses with
`no_display`, this session cannot show a window: tell the user to run
`graphide` (Linux) or open Graphide from Applications (Mac) on their own
desktop.

The first time Graphide opens a project it builds the map, which takes from
under a minute to a few minutes on a large repository; the window shows the
progress.

## What to say at the end

"Graphide is installed and open on this project. Start it again any time
with `gr app open`, or from your applications menu. Graphide tells you when
an update is out and installs it for you."

## Troubleshooting

- `gr daemon status` says whether Graphide's background service is running.
- `gr app status --json` shows the installed version and whether a newer one
  is out; `gr app rollback` goes back to the version before an update.
- On Linux, a warning that no Vulkan driver was found means the window cannot
  draw: the user needs their GPU's Vulkan driver (on Ubuntu,
  `mesa-vulkan-drivers`).
- `gr report` collects logs for a bug report.