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 no SDK to learn. Your agent is plain LangGraph that reads three environment variables. 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. 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
• warnings, never failures, for tool names or network libraries in your code that the manifest does not declare

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.

gravity schedule

Run the agent on its triggers.schedule, the way the platform will, until you press Ctrl+C. Each tick is an ordinary run with the same inputs.

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, GRAVITY_DEV_TOKEN and a reachable gateway. 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/ and tests/. 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.

gravity build && gravity push

gravity agents

List your published agents with their version, status and last update.

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 a description and the access each one needs.

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.

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

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 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, local time
    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

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}