# How to Set Up and Use the antigravity-cli Provider in ModLens

> Learn how to set up and use the antigravity-cli provider for ModLens. Process images with Google Gemini in 15-45 seconds using this keyless backend.

- Repository: [liustack/modlens](https://github.com/liustack/modlens)
- Tags: how-to-guide
- Published: 2026-08-25

---

**The antigravity-cli provider is the default, key‑less vision backend for ModLens that wraps the local `agy` binary to process images through Google's Gemini model in 15–45 seconds without requiring an API key.**

The `antigravity-cli` provider (also aliased as `agy` or `antigravity`) serves as the zero-configuration default in the [liustack/modlens](https://github.com/liustack/modlens) repository. It enables free image analysis by spawning a local subprocess rather than calling paid APIs directly, making it the go-to option for users who want to avoid managing cryptographic keys while still receiving structured JSON output conforming to the ModLens schema.

## Architecture and Implementation

The provider is implemented across four distinct layers in the codebase.

**Provider Registration** occurs in [`src/providers/index.ts`](https://github.com/liustack/modlens/blob/main/src/providers/index.ts), which registers the `antigravityCliProvider` object under the names `antigravity-cli`, `agy`, and `antigravity`. This registration exposes a unified `VisionProvider` interface that the analyzer consumes.

**Subprocess Orchestration** lives in [`src/providers/antigravity.ts`](https://github.com/liustack/modlens/blob/main/src/providers/antigravity.ts). This file defines the `buildAntigravityInvocation` function to construct the command line and `parseAntigravityOutput` to parse stdout. These are exposed via the `buildInvocation` and `parseOutput` fields of the provider object.

**Analyzer Integration** happens in [`src/analyzer.ts`](https://github.com/liustack/modlens/blob/main/src/analyzer.ts), which selects `antigravity-cli` automatically when no other provider is explicitly configured via the `-p` flag or environment variables.

**Result Validation** is handled by [`src/util/json.ts`](https://github.com/liustack/modlens/blob/main/src/util/json.ts) and [`src/schema.ts`](https://github.com/liustack/modlens/blob/main/src/schema.ts), which validate the JSON returned by the CLI against the ModLens schema and record timing metadata.

## Installation and Setup

### Install the Antigravity CLI

The provider requires the `agy` binary to be present on your system `PATH`. Install it via the official installer:

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

```

The provider’s availability check in [`src/providers/availability.ts`](https://github.com/liustack/modlens/blob/main/src/providers/availability.ts) simply verifies that `agy` can be found in `PATH` by attempting to spawn the process.

### Authenticate Once

Run the CLI interactively to complete the OAuth flow:

```bash
agy

```

This opens a browser window for Google authentication. After approval, credentials are stored in `~/.gemini/antigravity-cli/`. ModLens reuses this session automatically; subsequent runs do not require re-authentication unless the key-ring is locked or the weekly quota resets.

### No API Key Required

Because the Antigravity CLI handles authentication independently, ModLens does **not** need environment variables such as `ANTIGRAVITY_API_KEY` or `GEMINI_API_KEY`. This eliminates key management entirely for users who stick with this provider.

## Performance and Speed Characteristics

### Latency Benchmarks

The `antigravity-cli` provider exhibits **typical latency of 15–45 seconds per image**, depending on image complexity and current Gemini quota availability. This is significantly slower than the inline API providers (`gemini-api`, `openai`, `anthropic`), which return results in 5–10 seconds, because the subprocess incurs startup overhead and the free tier has lower priority queueing.

### Failover Behavior

Newer ModLens releases (v3.2+ and v3.17+) place inline API providers ahead of `antigravity-cli` in the automatic failover chain. If you have configured a paid API key, ModLens selects the 5–10 second path first and only falls back to `antigravity-cli` if the primary provider fails or is unavailable.

## Usage Examples

### Default Provider Selection

When no provider is specified, ModLens defaults to `antigravity-cli` as implemented in [`src/analyzer.ts`](https://github.com/liustack/modlens/blob/main/src/analyzer.ts):

```bash
modlens -i screenshot.png

```

No `-p` flag is required. The tool automatically detects that `agy` is available and routes the image through it.

### Explicit Provider Selection

To force the use of the CLI even when other providers are configured:

```bash
modlens -i screenshot.png -p antigravity-cli

```

This bypasses the failover chain and guarantees the subprocess-based execution.

### Custom Model Configuration

You can adjust the Gemini model used by the CLI through the ModLens configuration system:

```bash
modlens config set providers.antigravity-cli.model gemini-3.1-pro-high
modlens -i complex-diagram.png

```

The `buildAntigravityInvocation` function in [`src/providers/antigravity.ts`](https://github.com/liustack/modlens/blob/main/src/providers/antigravity.ts) injects this model parameter into the subprocess arguments.

### Inspecting Timing Metadata

To verify the exact latency for a specific run:

```bash
modlens -i screenshot.png --json | jq '.meta.attempts'

```

Expected output showing the 15–45 second window:

```json
[
  {
    "provider": "antigravity-cli",
    "ok": true,
    "durationSeconds": 27.3
  }
]

```

The `durationSeconds` field reflects the total time spent in `buildInvocation` through `parseOutput`.

## Troubleshooting Common Issues

| Symptom | Root Cause | Resolution |
|---------|------------|------------|
| `agy not on PATH` error from `modlens doctor` | Binary not installed or not in `PATH` | Re-run the install script or manually add the install directory to your shell configuration. |
| "not logged into antigravity" | Missing or expired session | Execute `agy` manually to re-authenticate; inspect logs at `~/.gemini/antigravity-cli/log` for OAuth errors. |
| Quota exhausted message | Weekly free tier limit reached | Switch to a paid provider via `modlens config set provider gemini-api` or wait for the quota reset. |

## Summary

- The **antigravity-cli** provider offers a free, zero-API-key solution for ModLens users by wrapping the local `agy` binary.
- Expect **15–45 seconds per image**, slower than paid alternatives but cost-free.
- Core logic resides in [`src/providers/antigravity.ts`](https://github.com/liustack/modlens/blob/main/src/providers/antigravity.ts) with registration in [`src/providers/index.ts`](https://github.com/liustack/modlens/blob/main/src/providers/index.ts).
- Requires one-time installation of the Antigravity CLI and browser-based authentication.
- Automatically selected when no other provider is configured, or explicitly via `-p antigravity-cli`.

## Frequently Asked Questions

### How does antigravity-cli differ from the gemini-api provider?

The **antigravity-cli** provider spawns a local subprocess (`agy`) that handles its own authentication and quota management, resulting in 15–45 second latency but requiring no API key. The **gemini-api** provider makes direct HTTPS calls to Google's API using a user-supplied key, delivering results in 5–10 seconds but requiring paid credentials stored in ModLens configuration.

### Why is my antigravity-cli provider taking longer than 45 seconds?

Extended latency usually indicates **quota exhaustion** on the free tier or **high image complexity** (resolution or token count). Check `~/.gemini/antigravity-cli/log` for rate-limit errors. If the quota is depleted, you must wait for the weekly reset or switch to a paid provider like `gemini-api`.

### Where does ModLens verify that the agy binary is installed?

The availability check occurs in [`src/providers/availability.ts`](https://github.com/liustack/modlens/blob/main/src/providers/availability.ts), which attempts to locate the `agy` executable in the system `PATH`. If the binary is missing, the provider is marked unavailable and ModLens skips it during provider selection unless explicitly requested with `-p antigravity-cli`.

### Can I use antigravity-cli without installing the agy binary?

No. The provider is strictly a wrapper around the local Antigravity CLI. Unlike API-based providers that only need an environment variable, this provider requires the `curl -fsSL https://antigravity.google/cli/install.sh | bash` installation step to place the binary on your `PATH` before ModLens can invoke it.