Gravity CLI

The command-line tool for building, testing and publishing AI agents on Gravity.
Write ordinary LangGraph in Python, declare what your agent may touch in one manifest,
and run it against real tools with exactly those permissions enforced.

Install · Quick start · Commands · Configuration · Manifest · Troubleshooting

gravity run on an agent that called a tool it never declared. The gateway refused that one call, and the run carried on:

  inbox-digest@1.0.0  run grt_…4e7b · 2 tools declared

  ● read                                                          0.9s
    ✓ gmail.read              3 found                             0.8s
  ● digest                                                        2.3s
    ◆ openai/gpt-6-luna                                           2.1s
    ✗ slack.send              refused — not in permissions.tools  0.0s

  ╭─ result ───────────────────────────────────────────────────╮
  │ unread    3                                                │
  │ headline  Two invoices and a meeting request need replies. │
  ╰────────────────────────────────────────────────────────────╯

  ✓ Done in 3.3s

pipx install gravity-cli
gravity init my-agent

Status. login, push, run and the tool catalog work out of the box against Gravity's hosted services. gravity login issues you the gateway token that run needs; nothing goes in .env.

Contents

• Declare it once, enforced on every call
• What is in the box
• Five things to know before you start
• Installation
• Quick start
• How it fits together
• Command reference
• Configuration
• Authentication
• The manifest
• An agent project
• Running a local gateway
• Troubleshooting
• Limitations
• Development
• Documentation

Declare it once, enforced on every call

There is almost no SDK to learn. Your agent is plain LangGraph that reads three environment variables; the one Gravity package, gravity, is preinstalled on the platform and is only needed to load approval-gated tools. Everything Gravity enforces comes from manifest.yaml:

The same rules apply on your laptop and when the agent runs hosted, because both go through the same gateway.

What is in the box

Five things to know before you start

• Inputs arrive in state["inputs"]; whatever you put in state["result"] is what the consumer gets.
• graph is an async def factory. Read environment variables inside it, never at import time.
• A tool that is not in permissions.tools is refused, whatever your code does.
• A tool listed in approvals.required_for waits for a yes in the terminal before it runs.
• The platform runs Python 3.12. gravity init writes that, and gravity validate fails on anything else.

Installation

Requires Python 3.12 or newer. Agents use uv for their own environments.

pipx install gravity-cli       # recommended: gravity gets its own environment
uv tool install gravity-cli    # the same, with uv
pip install gravity-cli        # into the current environment

gravity then works from any folder. To upgrade: pipx upgrade gravity-cli or uv tool upgrade gravity-cli.

If pip answers No matching distribution found for gravity-cli, your Python is older than 3.12 (check with python --version; conda's base often is). uv tool install gravity-cli avoids the problem, because uv fetches a suitable Python by itself. With pip, pick a newer interpreter: py -3.12 -m pip install gravity-cli on Windows, or python3.12 -m pip install gravity-cli elsewhere.

The first time you run gravity, it shows a short welcome and offers to create your first agent.

Quick start

1. Create and check an agent. No account or setup needed:

gravity init my-agent
cd my-agent
uv venv && uv pip install -r requirements.txt
gravity validate

2. Run it. Needs a gateway and your dev token, see Configuration:

gravity run --input query="hello"

3. Publish it. Needs a Gravity account:

gravity build
gravity login
gravity push

How it fits together

 your machine                                        Gravity
 ────────────                                        ───────
 gravity init / validate / build                     (nothing leaves your machine)

 gravity run ────── dev token ──────────────────→   gateway ──→ tools (MCP) and models (/v1)
    └─ starts your agent with a run token ──────→   gateway     only the declared tools are allowed

 gravity login / push / tools / agents ─────────→   control plane ──→ builds and hosted runs

On gravity run, the CLI trades your dev token for a run token scoped to the manifest's tools and starts the agent with only that token. Your own tokens are removed from the agent's environment, so agent code can never act as you.

Command reference

Run gravity help for this list in the terminal, and add -h to any command for its options.

gravity --api-url URL <command> saves a different control-plane address to ~/.gravity/config.json; it must start with http:// or https://. The flag applies to the command it is given with; on later commands a GRAVITY_API_URL in ~/.gravity/.env or the shell still wins over config.json, and the CLI says so when that is the case. gravity --version (or -V) prints the installed version. Wherever a command takes [path], it is the agent's folder and defaults to the current one.

gravity init

Create a new agent that already runs: a filled-in manifest, pinned dependencies and a working src/agent.py.

gravity init [name] [--template TEMPLATE] [--here]

gravity init inbox-digest
gravity init support-bot --template chat
gravity init --here

It refuses to overwrite an existing folder or manifest.yaml.

gravity validate

Check an agent on your machine, with no Gravity service involved. It reports every problem at once, each with a suggested fix.

gravity validate [path]

What it checks:

• manifest.yaml is valid, field by field
• the entrypoint file exists and defines the object the manifest names
• requirements.txt exists, and compiles into requirements.lock for the platform image (ARM64 Linux) and the manifest's Python version
• every adapter a slot declares has a file, and every adapter file is declared
• every tool in the manifest exists in the catalog, the same list the platform's build uses, so a typo fails here instead of after a push
• every imported write tool is under approvals.required_for
• your code never names a write tool the manifest does not grant
• a warning, never a failure, for read tools your code names but the manifest does not declare
• graph is an async def (or a compiled graph), not a plain def or a bare value; a name bound by an import counts
• nothing under src/ reads os.environ or calls asyncio.run at module level, and no import is relative
• a schedule runs at most every 5 minutes and restricts the day of the month or the weekday, not both

gravity validate
gravity validate ./my-agent

Exits with code 1 if anything is wrong.

gravity run

Run the agent locally through the gateway and watch it live: each step, model call and tool call, then a result card.

gravity run [path] [--input KEY=VALUE]... [--reply TEXT] [--llm-url URL]

gravity run --input query="summarise my unread email"
gravity run --input transcript=@call.txt --input tone=formal
gravity run --reply "make it shorter"

• Requires a gateway token: the one gravity login stores, or GRAVITY_DEV_TOKEN.
• A call to a tool in approvals.required_for pauses, shows what it would do, and waits for y or n. With no terminal to ask in, it is rejected.
• Exits with code 0 when the run finishes and 1 when it fails.
• Leaves a record in .gravity/runs/<id>/ (run.json and events.jsonl), which is what gravity dev reads. One run is live per folder at a time, because runs share the folder's memory, store and thread files.

gravity dev

Open a local dashboard for the agent in this folder: a form built from the manifest's inputs, a live timeline of each step, model call and tool call, approval buttons for held calls, the result, and a history of runs.

gravity dev [path] [--port 4747] [--no-open] [--llm-url URL]

• A run from gravity run in the same folder shows up in the dashboard live, and a run started in the dashboard is the same run (same engine, same memory, store and thread files), so gravity run --reply continues it.
• It listens on 127.0.0.1 only, behind a random token in the printed address, for as long as the command runs. Ctrl+C stops it and any run it started. Nothing keeps running in the background.
• Connected accounts: it shows the accounts your tools need and a Connect button for each one that is missing.
• Approvals: a call held for approval can be decided in the terminal or in the dashboard; whichever answers first wins.
• Cancel a run from the dashboard only if the dashboard started it; stop a terminal run with Ctrl+C in that terminal.
• Results show as text. Word, PowerPoint and CSV files are produced by Gravity after you push. A file input is read as text here.
• Same requirements as gravity run: a gateway token from gravity login, or GRAVITY_DEV_TOKEN.

gravity schedule

Run the agent on its triggers.schedule, the way the platform will, until you press Ctrl+C. Ticks are timed in Asia/Kolkata, as the hosted schedules are. Each tick is an ordinary run with the same inputs; a missing required input is refused before the first tick.

gravity schedule [path] [--input KEY=VALUE]... [--cron EXPR] [--now]

gravity schedule --input send_to=me@example.com
gravity schedule --cron "*/30 * * * *" --now

Nobody is at the terminal during a scheduled run, so calls that need approval are rejected and the agent takes its fallback. A failed run does not stop the schedule.

gravity adapt

Have a coding agent write one new adapter for a slot. The file is kept only if the slot's conformance tests pass; otherwise the file and the manifest are put back as they were.

gravity adapt <slot> <name> --tools TOOLS [--hint TEXT] [--model MODEL] [--path PATH]

gravity adapt deliver slack --tools slack.send,slack.list_channels --hint "post to #leads"

Requires tests/test_<slot>_adapters.py in the project and a gateway token (gravity login, or GRAVITY_DEV_TOKEN). It makes up to 3 attempts, feeding each test failure back to the model.

gravity build

Validate the agent, then bundle it into build/agent.zip with its hashes in build/build.json. Nothing leaves your machine, so you can inspect the zip before publishing.

gravity build [path]

The bundle holds manifest.yaml, requirements.txt, requirements.lock, src/, tests/ and tools_needed.yaml when present; dotfiles under src/ and tests/ are left out. It refuses to build without requirements.lock (run gravity validate first). The same source always produces the same bytes.

gravity build

gravity push

Upload exactly what gravity build made, then wait while Gravity builds it.

gravity push [path]

• Requires gravity login, or GRAVITY_API_TOKEN for development.
• Refuses if there is no build, or if the source changed since the build. Run gravity build again.
• A published version can never be replaced. Raise version in the manifest to publish again.
• Press Ctrl+C to stop waiting; the build carries on, and gravity agents shows its status.
• The bundle may be at most 30 MB; a larger agent.zip is refused before upload. Remove large files from src/ or tests/ and build again.
• The manifest travels in a request header, so manifest.yaml must stay under 12 KB once encoded; a larger one is refused before upload. Keep descriptions and help text short.
• Re-pushing a version whose build failed, without changing the source, is refused with the failure reason: fix it and raise version in the manifest.

gravity build && gravity push

gravity agents

List your published agents with their version, status, review and last update. Under the table it prints what the Gravity team told you: the reviewer's notes on an approved or rejected version, and the reason if an agent was turned off. A rejected version needs a fix and a new version: in manifest.yaml before you push again. A failed build prints its reason under the table.

gravity agents

gravity runs

Show recent hosted runs of one agent, with status, start time and cost.

gravity runs <agent_name>

gravity runs inbox-digest

gravity logs

Show the logs of one hosted run. The run id comes from gravity runs.

gravity logs <run_id>

gravity tools

Browse the tool catalog: the names you can put under permissions.tools, with what each one does. It is the gateway's own list, so it shows exactly what a run can call, and it needs no sign-in.

31 tools are curated, such as gmail.read and web.search. The other ~1,370 are imported from the same apps and unreviewed: any imported tool that changes something must also be under approvals.required_for, and gravity validate checks that.

gravity tools [search]

gravity tools           # everything
gravity tools gmail     # only tools whose name contains "gmail"

gravity login

Sign in to Gravity. It opens your browser, shows a short code to confirm, and stores the session in your operating system's keychain.

gravity login

gravity logout

Remove the stored session.

gravity logout

gravity whoami

Show the account you are signed in as, and whether you hold a gateway token and until when (an expired one is a warning).

gravity whoami
gravity whoami --token    # print the gateway token itself, for CI or a teammate's .env

gravity connect

Connect an account your agents' tools act on, through the app's own sign-in page in your browser. With no app, list what is connected.

gravity connect [app]

gravity connect           # what is connected, and whose accounts runs act on
gravity connect gmail     # opens the sign-in page, then waits until it is done
gravity connect sheets    # use the app name from tool names: sheets, calendar, drive, linear, slack, github...

• Uses the gateway token from gravity login.
• web tools need no account.

gravity guide

Read the builder guide, which ships with the CLI: how an agent is put together, the rules your code must follow, formatting results, approvals, adapters, scheduling, memory, and a checklist.

gravity guide [--save]

On a terminal it asks which section you want. Piped, it prints the whole guide.

gravity guide
gravity guide --save
gravity guide | less

gravity docs

Write or refresh the two files a coding agent needs to build for Gravity in this folder: Gravity.agent.md (how Gravity runs agents, the manifest, every tool this release knows, the output formats, the rules that fail a load) and problem-to-agent.md (the method for turning a problem statement into an agent that holds up).

gravity docs [--force]

You rarely need this. Every command writes the two files into the folder it runs in if they are missing (never into your home folder or a drive root; gravity init writes them into the new agent), and rewrites them when a newer release changes them. The first line of a file Gravity wrote names the release and a hash of the text after it: if you edit the file the hash no longer matches and Gravity leaves it alone. Your own agent.md, AGENTS.md and CLAUDE.md are never touched. Point your coding agent at Gravity.agent.md from them if it does not look there by itself. Set GRAVITY_AGENT_DOCS=0 to stop the automatic writes.

gravity update

Check PyPI for a newer release, install it, and show what is new.

gravity update [--check]

You do not have to run it: once every six hours a command looks for a newer release, and when there is one it says Update available 0.6.0 → 0.6.1, updates, and runs your command again as the new version, which lists what changed. It upgrades the way you installed it (uv tool or pipx); a copy installed any other way, or from a source checkout, is told the command to run and left alone. Nothing here can stop a command: a failed update is one warning and the command runs on the version you have. Set GRAVITY_AUTO_UPDATE=0 to turn the check and the install off; CI never updates.

gravity changelog

What changed in each release, written for builders.

gravity changelog [--all]

gravity help

Show the list of commands. The same as gravity -h.

gravity help

Configuration

Where settings live

Put them in ~/.gravity/.env (on Windows, %USERPROFILE%\.gravity\.env). Every gravity command loads this file, from any folder, so you set a value once. With Gravity's hosted services, gravity login is all you need, and the file can stay empty.

# ~/.gravity/.env
GRAVITY_DEV_TOKEN=<a gateway token, only if gravity login did not issue you one>

That is the only setting most builders ever need. The CLI knows where Gravity's control plane is, and asks it where the gateway is.

When a setting is given in more than one place, the first match wins:

1. a variable exported in your shell
2. ~/.gravity/.env
3. ~/.gravity/config.json (only the API address, written by gravity --api-url URL <command>)
4. the built-in default

Never commit a .env file. The .gitignore in every template keeps .env and .gravity/ out of git.

What each task needs

Set GRAVITY_API_URL and GRAVITY_GATEWAY_URL only to work against services you run yourself; see Running a local gateway.

Environment variables

What your agent receives

gravity run starts your agent with exactly these three, and the hosted runner does the same. You never set them yourself:

Authentication

Two separate credentials, for two separate services:

gravity login stores the session and gateway token in the operating system's keychain. On machines without one, it falls back to ~/.gravity/session.json, readable only by you. gravity logout removes it.

For development, setting GRAVITY_API_TOKEN to the control plane's dev token skips login. gravity whoami then prints the dev user's id followed by (dev token).

The manifest

manifest.yaml declares everything about the agent that Gravity enforces. Only name and runtime.entrypoint are required; everything else has a default.

The smallest useful manifest:

contract: v1
name: my-agent
version: 1.0.0
runtime:
  entrypoint: src/agent.py:graph
inputs:
  - name: query
    type: text
    label: "What should the agent do?"
    required: true
permissions:
  tools: [example.echo]

contract: v1                      # manifest contract version; v1 is the only one
name: inbox-digest                # lowercase letters, digits, single hyphens; appears in URLs
version: 1.0.0                    # semver; a published version is frozen, so bump it to publish again
description: "Summarises unread email and sends a digest"
kind: interactive                 # transform | interactive | monitor

runtime:
  framework: langgraph            # the only framework in v1
  python: "3.12"                  # the platform image runs Python 3.12
  entrypoint: src/agent.py:graph  # file:object, relative to the project folder
  timeout_seconds: 300            # 10 to 28800

dependencies:
  lockfile: requirements.lock     # written by `gravity validate`

inputs:                           # each becomes a field in the consumer's form
  - name: lookback
    type: static-dropdown
    label: "How far back?"
    options: ["1 day", "7 days"]
    default: "1 day"
  - name: send_to
    type: email
    label: "Send the digest to"
    required: true

permissions:
  tools:                          # the only tools this agent's runs may call
    - gmail.read
    - gmail.send
  models:
    tier: standard                # standard | premium

approvals:
  required_for:                   # these calls pause until a person approves them
    - gmail.send

resources:
  memory_mb: 512                  # 128 to 4096; a request the platform may lower

triggers:
  manual: true                    # the consumer can start a run
  schedule:
    cron: "0 8 * * 1-5"           # weekdays at 08:00, Asia/Kolkata
    consumer_can_change: true

state:
  max_kb: 64                      # memory kept between runs (1 to 256 KB); omit for none

slots:                            # a part the consumer chooses; each adapter gets only its own tools
  deliver:
    label: "Where should the digest go?"
    default: email
    adapters:
      email: [gmail.draft]        # code in src/adapters/deliver/email.py
      slack: [slack.send]         # code in src/adapters/deliver/slack.py

outputs:                          # extra formats the platform renders and delivers itself
  report:
    renderer: markdown            # markdown | docx | pptx | rows
    label: "Digest as a document"
    destinations: [download]

Field reference

Unknown fields are rejected rather than ignored, so a typo is reported instead of silently dropped.

An agent project

my-agent/
├── manifest.yaml       what the agent is and may do
├── requirements.txt    your dependencies
├── requirements.lock   compiled by `gravity validate`; commit it
└── src/
    └── agent.py        exports `graph`, an async factory returning a compiled LangGraph graph

Files the CLI writes:

The template .gitignore excludes build/, .gravity/ and .env.

Running a local gateway

The gateway belongs to the Gravity platform repository and is run by the Gravity team. Builders outside the team use the hosted gateway instead.

GRAVITY_DEV_TOKEN=<the gateway's LOCAL_DEV_TOKEN>
GRAVITY_GATEWAY_URL=http://127.0.0.1:8000/mcp
GRAVITY_API_URL=http://localhost:3010
GRAVITY_API_TOKEN=<the control plane's PLATFORM_DEV_TOKEN>

Troubleshooting

What's new

• 0.6.0 Gravity CLI keeps itself up to date and says what changed (gravity update, gravity changelog). Gravity.agent.md and problem-to-agent.md appear in the folder you work in, for your coding agent (gravity docs). gravity on its own shows your version, the agent in the folder, whether you are signed in, and any update. The notes shown after an update are src/gravity_cli/CHANGELOG.md.
• 0.5.5 manifest.yaml takes an optional display: hint for how a run's result shows: view (document, report, table, chart, code or files), field (the result key to show) and chart (type: line or bar, x, and up to three y fields). It is a hint, never a rule: an unknown view or key is ignored, so it never fails a push. 0.5.4 and earlier refuse a manifest that has it.
• 0.5.4 gravity agents shows each agent's review: a REVIEW column (not submitted, submitted, approved, rejected), and under "From the Gravity team" the reviewer's notes and what to do next. An agent the Gravity team turned off shows as off with the reason. UPDATED reads "3 min ago" instead of a timestamp, and status and review are coloured. Also, from a full audit of every command: gravity --version. Clear messages instead of tracebacks for: a proxy or sign-in page answering instead of Gravity, a refused GRAVITY_API_TOKEN or GRAVITY_DEV_TOKEN, an expired sign-in code, a non-UTF-8 manifest, an out-of-range --port, a missing agent folder, a malformed session file. gravity validate now refuses what the build would refuse: a graph that is not an async factory, os.environ or asyncio.run at import, relative imports, unquoted python: 3.12, schedules faster than every 5 minutes or with both day fields, out-of-range cron fields; it accepts a re-exported graph. gravity agents shows the review status and failure reasons; gravity runs never shortens an id; gravity logs never wraps. gravity push refuses a bundle over 30 MB or a manifest over 12 KB before uploading, and says why when a failed version is re-pushed. gravity build ships tools_needed.yaml, leaves dotfiles out, and refuses to build without requirements.lock. gravity adapt leaves the folder untouched when a model call fails. gravity schedule checks inputs before the first tick and runs on Asia/Kolkata like the hosted schedules. gravity run deletes .gravity/payload.json after the run, warns when no .venv is present, and keeps a plain agent's result. gravity connect <app> refuses on the shared test account instead of attaching your account to it. The builder guide and agent standard describe the real flow (init, validate, run or dev, build, push, review on /app).
• 0.5.3 gravity dev opens a local dashboard for your agent: a form from your manifest, a live timeline, approvals, the result and run history; runs from gravity run in the same folder show up in it live, and the other way round. WhatsApp joins the catalog (51 tools; 1,402 across 15 apps including the curated and built-in ones). Agents can return generated images: put them in a corpus section's images and they land in the Word, PowerPoint and Markdown outputs. The agent standard now shows how to generate images and embeddings through the gateway. NEEDS_RECONNECT on the shared test account tells you to ask Gravity, not to connect your own account.
• 0.5.2 Jira, Confluence and Notion join the catalog: 1,351 tools across 11 apps. get_store() works in local runs, kept in .gravity/store.json. Renewing an expired sign-in keeps your gateway token, so gravity run keeps working after an hour. Commands start faster: the catalog loads in a quarter of the time.
• 0.5.0 gravity connect links your own accounts. web.search and web.fetch join the catalog. gravity validate now refuses a tool that isn't in the catalog, an imported write tool without an approval, and code that names a write tool the manifest doesn't grant. gravity tools reads the gateway's list and needs no sign-in. On Windows the session stays in the keychain instead of a file.
• 0.4.4 Same code as 0.4.3, released from this repository so the GitHub release, the tag and PyPI line up again. Adds RELEASING.md.
• 0.4.3 Documents the secret input type and the supadata.get_transcript tool.
• 0.4.1 New input type secret for an API key, password or other confidential value. New built-in tool supadata.get_transcript (gravity tools supadata).

Limitations

• No offline mode. gravity run always talks to a real gateway. There is no mock-tool mode.
• Heuristic drift check. gravity validate finds undeclared tools by scanning source for imports and tool-shaped strings. Expect some false positives; they are warnings, never failures.
• Models are not restricted yet. The gateway forwards whatever model name the agent asks for, and permissions.models.tier is not enforced.
• Hosted history. gravity runs and gravity logs show what the control plane returns, which is empty until an agent has hosted runs.

Development

git clone https://github.com/AIGravity/gravity-cli.git
cd gravity-cli
uv sync                                                   # both packages and the dev tools
uv run gravity --help
uv run pytest                                             # CLI tests
cd packages/gravity-schema && uv run pytest && cd ../..   # manifest contract tests
uv run ruff check .

The repository holds two packages that are always released together at the same version:

After changing the manifest model, regenerate the committed JSON Schema with uv run python -m gravity_schema. A test fails until you do.

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ gravity-cli==0.2.0rc1

uv run python -m gravity_schema.gen_catalog --root <platform repo>/code-first

Documentation

_{PyPI · Apache License 2.0 · Copyright 2026 AIGravity · See LICENSE and NOTICE}