Installation & setup¶
Install the CLI from PyPI, give your coding agents the six
skills, and let login tell you what is still missing before you create a
project.
Released on PyPI
graph-agents-cli is on PyPI from 0.3.1:
uv tool install graph-agents-cli. Earlier releases (0.1.0 to 0.3.0) are git tags only.
The six skills it installs are tuned with SkillOpt; see the
skills benchmark.
Prerequisites¶
You need Python and uv for everything; the rest only for the stage that uses it.
| Tool | Needed for |
|---|---|
| Python 3.12 or 3.13 | The CLI and every project it generates |
| uv | Installing the CLI; install, run, playground, lint and eval run the project through it |
Node.js (npx) |
setup and update install the skills with npx skills; without it setup copies them instead |
helm, kubectl, a Docker-compatible docker CLI that builds with BuildKit, git |
build, deploy and secrets. The generated Dockerfile uses RUN --mount, which needs BuildKit (the buildx plugin; the default in Docker Desktop) |
gh |
Argo CD mode (deploy opens pull requests) and GitHub-hosted CD |
Everything up to deployment runs on your machine. A tool that deploy needs and cannot
find on PATH makes it exit 2.
Install the CLI¶
Install the PyPI package with uv tool:
uv tool upgrade graph-agents-cli moves to the latest release later. Other installers work
too:
Put ~/.venvs/graph-agents-cli/bin on your PATH, or call the CLI by its full path.
The same release, built from its git tag: what setup, update and generated projects'
CI install (see Install sources).
Optional extras¶
Two commands need an extra dependency:
| Extra | For |
|---|---|
a2a |
run --mode a2a (talk to an agent over A2A JSON-RPC) |
langsmith |
eval submit (upload a dataset and results to LangSmith) |
uv tool install 'graph-agents-cli[a2a,langsmith]'
# or from the release tag
uv tool install 'graph-agents-cli[a2a,langsmith] @ git+https://github.com/ss7172/graph-agents-cli@v0.3.1'
Which build you are running¶
--version names the build, and info adds the full commit:
--version prints |
Meaning |
|---|---|
0.3.1 |
The release, built from the v0.3.1 tag |
0. |
A build of another commit (a checkout between releases) |
0. |
A build with uncommitted changes |
Every project records the build that created it, which is what
scaffold upgrade replays later. To install a build from a
source checkout, see
Installing a build from a checkout
in CONTRIBUTING.md.
Install the skills¶
setup installs the six skills into the coding agents it finds
(Claude Code, Codex, Gemini CLI, Cursor, Antigravity and others), so you can ask your agent
to "use graph-agents-cli to build ...". It also runs uv tool install for the pinned CLI
from its release tag: nothing changes when that is already installed, and a CLI installed
from PyPI is replaced by the same release built from the tag (see
Install sources).
Repeat --agent for each one; --agent all installs for every agent that
npx skills supports.
Preview any of these with --dry-run, which prints the commands and changes nothing:
1. Dry Run
──────────
Would install graph-agents-cli:
▸ uv tool install git+https://github.com/ss7172/graph-agents-cli@v0.3.1
Would install skills:
▸ npx -y skills@1.5.9 add 'https://github.com/ss7172/graph-agents-cli#v0.3.1' -y -g
(falls back to the bundled skills, then to a copy into ~/.agents/skills)
Scope: global
No changes made (dry run).
Where the skills come from¶
The skills match the release your CLI's version names. setup tries three sources in
order, each only when the one before it fails:
npx skills addfrom this repository at that release's tag (https://github.com/ss7172/graph-agents-cli#v0.3.1). Needsgitand network access.npx skills addfrom the copy bundled in the installed CLI (same build, no network).- A plain copy of the bundled skills into
~/.agents/skills(./.agents/skillswith--workspace), for machines without Node.js.
A build between releases (0.3.1+g<commit>) still installs the v0.3.1 skills in step 1.
Only a version with no release behind it (0.0.0, a .devN or a +local version) uses the
default branch. For skills that match a checkout's own code, run setup --dev from the
checkout (it also installs the CLI from it, editable) or pass --skills-source <checkout>.
--skills-source names another source instead: a local path, a GitHub owner/repo, or a
URL with a #<ref>. An explicit source never falls back to the bundled copy.
Antigravity
A global setup also links the skills into the directories Antigravity reads
(~/.gemini/config/skills and ~/.gemini/antigravity-cli/skills) when ~/.gemini
exists, because npx skills installs global skills into ~/.agents/skills.
The CLI stores no credentials: setup never asks for a key. See
setup in the CLI reference for every flag,
including --dev for contributors.
Keep up to date¶
update refreshes the installed skills, then reinstalls the CLI from the latest GitHub
release when it is newer than the one you run (best effort: offline, it leaves the CLI as
it is) and moves the skills to that release's tag, so the two stay in step. Add -i to
confirm before it starts.
The CLI also checks GitHub for a newer release at most once every 12 hours and prints an
"Update available" line when there is one. Set GRAPH_AGENTS_CLI_NO_UPDATE_CHECK=1 to turn
the check off, for example on a machine without internet access.
Check your environment¶
login is a preflight, not a sign-in: it reads the process environment and the project's
.env, reports what is missing, and stores nothing. Run it inside a project; the
Quickstart does that right after create.
| Check | Passes when |
|---|---|
provider, provider_key |
The provider's key is set (OPENAI_API_KEY, ANTHROPIC_ or GOOGLE_API_KEY); for openai-compatible, OPENAI_BASE_URL is set (whether it answers is reported as advice) and MODEL_API_KEY is optional |
api_key |
Under the shared-bearer auth policy, API_KEY is set (without it the local server answers 503) |
jwt_key, jwt_token |
Under jwt, a verification key is set and GRAPH_ holds a token for run and eval |
env_file |
.env is not readable by other users |
judge |
The eval judge's provider and key, when JUDGE_ is set |
tracing |
With TRACING_, LANGSMITH_ or an OTLP endpoint is set |
kubeconfig |
kubectl has a current context (--cluster also checks that the cluster answers) |
--write-env fixes what it can: it prompts for missing keys without echoing them, fills
blank KEY= lines of .env in place, generates an API_KEY for a shared-bearer project
and leaves .env at mode 0600.
| Flag | Effect |
|---|---|
--status |
Print the report and exit 0 even when a check fails |
--json |
Print the report as JSON |
--cluster |
Also run kubectl cluster-info against the current context |
--profile disconnected |
Fail on every hosted dependency (see Offline profile) |
--env-file FILE |
Read (and write) another env file |
Without --status, a failed check makes login exit 1, so a script or a coding agent can
stop there.
Install sources¶
setup, update, the scaffold upgrade baseline and the CI of every generated project
(GRAPH_AGENTS_CLI_SPEC in its .github/agent.env) install the CLI from the same pinned
git tag, whichever way you installed it: every release is tagged, while releases before
0.3.1 are not on PyPI. GRAPH_AGENTS_CLI_INSTALL_SPEC points all of
them somewhere else: a private mirror, a wheel, or a package index. Write {version} where
the release number goes (git+https://git.example.com/graph-agents-cli@v{version}) so an
upgrade can install an older release; an override that cannot work is refused with exit 3.
GRAPH_AGENTS_CLI_INSTALL_SPEC='graph-agents-cli=={version}' installs from PyPI (or the
index UV_INDEX_URL names), for releases published there.
Environment variables has the full rules, and
Offline profile shows a complete disconnected setup.
Next steps¶
-
Create a project and talk to your first agent in five minutes, without a model key.
-
Let the skills drive the lifecycle while you review each step.
-
Every command and flag, generated from the CLI itself.