Antigravity CLI, step by step

This guide gives Antigravity CLI (command agy) the full orboto workflow through the orboto CLI: binding workspace rules on session start, ticket claims, timers, comments, the agent inbox. Follow it top to bottom; every step tells you what you should see before you move on. At the end you type "show me my open tickets" and it answers from your workspace.

1. Open a terminal and install both tools

• Mac: press Cmd + Space, type Terminal, press Enter.
• Windows: press the Windows key, type PowerShell, press Enter.

A window with a blinking cursor opens. Everything below that looks like code is typed into this window, followed by Enter.

First install Antigravity CLI (Google's terminal agent, the successor of Gemini CLI):

• Mac:

  curl -fsSL https://antigravity.google/cli/install.sh | bash

• Windows:

  irm https://antigravity.google/cli/install.ps1 | iex

Then install the orboto CLI:

• Mac:

  curl -fsSL https://raw.githubusercontent.com/orboto/orboto-cli/main/install.sh | sh

• Windows:

  npm install -g orboto

Wait until the cursor comes back, then close the terminal window and open a new one so both commands are found. Check:

orboto version

You should see a version number. If you see "command not found" or "not recognized", open a new terminal window and try again.

2. Sign in to Antigravity CLI

In the terminal type agy and press Enter. The first start asks you to sign in; your browser opens, log in with your Google account and confirm. Back in the terminal Antigravity shows a prompt box. Type /exit and press Enter to leave for now.

3. Create your orboto API key

The key is how the orboto CLI proves to orboto that it is you. It is a long text starting with orb_.

1. Open your orboto workspace in the browser and log in.
2. Click your avatar in the top-right corner, then Profile.
3. Scroll to the API Keys card and click New key.
4. Name it antigravity-cli. Tick This key is used by an AI agent - work done through it is then attributed as agent work in reports.
5. Click Create.
6. The key is shown once. Click the copy icon next to it and paste it somewhere safe for the next step (a notes app is fine for now, delete it afterwards). Then click I've saved it.

4. Log the CLI in

One command, replace the address with your workspace address:

orboto login --api-key --base-url https://YOUR-WORKSPACE

It asks for the API key from the previous step (the input stays hidden while you paste it, then press Enter), checks it with orboto and saves it to ~/.orboto/env. You see your name and e-mail address as confirmation:

orboto whoami

If orboto whoami prints an error, jump to If something does not work.

5. Let Antigravity CLI use it

Antigravity CLI runs terminal commands itself, so it can drive the orboto command you just configured. Start it inside the folder you work in and make the first message this (replace ACME with the key of your orboto project, the short prefix of your ticket numbers):

agy

Run "orboto session-start --project ACME" and follow the rules it prints. Then show me my open orboto tickets.

Antigravity CLI may ask you once to allow running the orboto command; allow it. session-start hands the agent the workspace rules (ticket first, one commit per ticket, how to claim, comment and close), and the agent answers with your tickets. From here on you can work as you would in the app:

• Which tickets in project ACME are blocked?
• Claim ACME-42 and start the timer.
• Add a comment to ACME-42: waiting for the design review.
• Close ACME-42 with a comment about what changed.

The agent only does what your orboto account may do. If you cannot delete a ticket in the app, it cannot either.

6. Start it through orboto

Added in v0.223.0 Once the steps above work, start Antigravity CLI with orboto agy instead of agy. orboto then stays the parent process and gives the session what orboto claude gives Claude Code:

orboto agy                                     # works on the project this folder belongs to
orboto agy --yolo --continue                   # no permission questions, the most recent conversation
orboto agy --role review --scope-projects ACME # declare the scope yourself
orboto agy -- --model <model>                  # everything after -- goes to agy

• Scope. The session registers with orboto and declares its role and project. Without flags it declares worker on the project of the folder you start in.
• MCP server and hooks. Before agy starts, orboto adds its MCP server to ~/.gemini/config/mcp_config.json and its hooks to ~/.gemini/config/hooks.json. Every other entry stays untouched, and orboto prints one line whenever it changes a file. The hooks only act inside a session that orboto agy started.
• Agent mail. New mail reaches the model before its next call, also in the middle of a long turn. A turn that is about to end continues when new mail has arrived. A session waiting at its prompt gets one line typed in, naming only the count and kind of the waiting messages, never their text. Nothing is typed before agy has reported its first state after a start or restart. Added in v0.230.0 The supervisor reads the inbox every 15 seconds, and that read keeps the session reachable: orboto who lists an orboto agy session as reachable by inbox stream. You run no Monitor and no orboto messages --follow beside it; with --no-supervise nothing wakes the session.
• Status line. Added in v0.226.2 orboto also adds its status line to ~/.gemini/antigravity-cli/settings.json. It reports the context fill and your quota windows to orboto. If you already have a status line of your own, orboto keeps it and runs it for you.
• Live view. Added in v0.226.2 Admin → Agents → Live shows the session as a conversation: prompts, answers, tool groups and a line per finished turn, with context fill and quota in the footer. After a restart it continues with the resumed conversation.
• Completion check. When a turn ends, orboto checks whether the session still owns work it is allowed and able to do, and lets the turn continue with the reason if so.
• Restart. orboto agy update --restart resumes exactly the conversation that was running. Added in v0.230.0 A second orboto agy in the same checkout gets a session token of its own and runs beside the first when its scope shares no project or ticket with it. A start inside 10 minutes of a session ending takes that session's row back only when it continues the same agy conversation with --resume <id> or --continue; the conversation id is recorded once the orboto session has declared its scope, at the start or later with orboto session-start. Any other start gets a row of its own, see One session per account, checkout and scope.
• Own identity. Log an agent key in as a profile and bind it once: orboto login --profile gemini --api-key, then orboto profile bind agy gemini. Every orboto call inside the session then runs as that bot.

You no longer need a hand-written PreInvocation hook for the inbox. agy keeps its Google sign-in in the system keyring, so login profiles and the account switch do not apply to it. orboto agy --help lists that gap with its reason. orboto agy unwire removes the MCP server, the hooks and the status line orboto wrote and restores a status line command of yours. More on the shared flags: Launchers and the uniform flags.

Where Antigravity CLI looks for things

• Skills: .agents/skills/<name>/SKILL.md in the project or ~/.gemini/antigravity-cli/skills/<name>/SKILL.md globally; the orboto skill ships with the YAML front matter it expects.
• Rules: GEMINI.md, AGENTS.md or .agents/rules/*.md, discovered walking up from the working folder - orboto init writes the orboto rules into AGENTS.md, which Antigravity reads as is.
• Hooks: .agents/hooks.json in the project or ~/.gemini/config/hooks.json globally (SessionStart, PreInvocation, PostInvocation, PreToolUse, PostToolUse, Stop). orboto agy writes its own hooks into the global file (step 6).
• MCP servers: ~/.gemini/config/mcp_config.json (see the alternative below).
• Antigravity's context window is large; the orboto MCP server still keeps every tool answer inside its response budget, so tool turns stay fast.

Alternative: connect through MCP

If you only want tool calls without the CLI workflow, Antigravity CLI can also talk to orboto's MCP server. Create ~/.gemini/config/mcp_config.json with {"mcpServers": {"orboto": {"serverUrl": "https://YOUR-WORKSPACE/mcp", "headers": {"Authorization": "Bearer orb_PASTE_YOUR_KEY_HERE"}}}}, then /mcp inside agy shows the server; without headers Antigravity runs the OAuth login instead. Everything about that path is on the MCP server page.

If something does not work

What next

• The complete command set is on CLI daily workflow; connection profiles for several workspaces on CLI profiles.
• To have Antigravity CLI work tickets on its own and get woken by other agents through the orboto inbox, see the agent inbox guide - that setup is for technical operators.
• While orboto messages --follow runs, the agent is listed as online in Admin → Multi-Agent; orboto agent-heartbeat adds what it is working on and its capabilities.