Using gr

gr is Graphide’s command line tool. It installs and updates the app, signs you in, builds and checks maps, answers questions about your code from the map, and connects the coding agents you run in a terminal. Every command talks to the daemon, the one background service Graphide runs for you.

Help

gr help              # every command, by name
gr help init         # one command in full
gr init --help       # the same

The command reference is the same help, grouped by task. For gr claude and gr codex use gr help claude: their --help goes to Claude Code and Codex.

Which project

A command acts on the project of the folder you run it in, found by climbing to the top of its git repository. Run it from anywhere inside the repository, or name the project with --root:

gr status --root ~/code/my-project

For scripts

Most commands take --json and print one JSON object instead of words. gr doctor exits with 0 when nothing needs attention, 1 when something does, and 2 when something is wrong.

The commands you will use most

Task	Commands
Set up	gr login, gr app install, gr app open ., gr version
Build the map	gr init, gr map, gr status
Ask the map	gr query, gr impact, gr code, gr outline, gr summary
Run an agent with the map	gr claude, gr codex, gr harness install
Work in worktrees	gr worktree new, gr worktree land
Fix something	gr doctor, gr report, gr logs

Ask the map from a terminal

gr query "who refreshes the session token"
gr impact internal/auth/session.go:Refresh --depth 2
gr code internal/auth/session.go:Refresh
gr summary

• gr query answers a question with a small, ranked slice of the map: the parts that matter and how they join. --budget sets how long the answer may be.
• gr impact lists who calls a symbol, and what a change to it breaks, hop by hop with file:line.
• gr code prints one symbol’s source, and gr outline a file’s symbols.
• gr summary prints the project’s architecture, its busiest parts, entry points and open questions, as Markdown, without calling a model.

A symbol is named by its file and name, path/to/file.go:Name, or path:Type.method for a method.

Worktrees

A worktree is another checkout of the repository on a branch of its own, so agents can work side by side without touching each other’s files. gr worktree makes worktrees that come with a map:

gr worktree new fix-login      # <checkout>-fix-login, on a new branch, with its map
gr worktree ls                 # every worktree, with its map's state
gr worktree land fix-login     # merge, push, remove the worktree

Shell completion

gr completion zsh > "${fpath[1]}/_gr"     # zsh
gr completion bash > ~/.local/share/bash-completion/completions/gr
gr completion fish > ~/.config/fish/completions/gr.fish

Which servers

gr talks to Graphide’s servers at graphide.com. gr env shows which servers this machine’s daemon uses, in case someone on your team has pointed it elsewhere.