Skip to main content

AntGravity CLI

AntGravity CLI Logo

A portable and interactive command-line interface (CLI) developed in Python to flexibly interact with agents from the Google Antigravity ecosystem.


Requirements

  • Python 3.11+
  • Installed dependencies (including google-antigravity, click, colorama, python-dotenv, rich, prompt-toolkit, and PyYAML).

Installation and Setup

Global Installation (via PyPI)

Install the package globally or in your virtual environment:

pip install AntGravityCLI

Once installed, you can run the CLI from anywhere using:

antgravity [options] [prompt]
# or the shortcut alias:
ant [options] [prompt]

Development Setup

  1. Clone the repository and navigate to the project folder.
  2. Make sure the virtual environment is activated:
    .\.venv\Scripts\activate
    
  3. Install package dependencies in editable mode:
    pip install -e .
    
  4. Configure your environment using a .env file by copying the template:
    cp .env.example .env
    

Running the Test Suite

The test suite has been restructured into a modular tests/ package. To run all tests and check for regressions, execute:

python -m unittest discover -s tests -p "test_*.py"

Click Subcommands

The CLI exposes two built-in subcommands:

1. Interactive Workspace Setup (init)

To initialize a new project workspace with the required folders (.agents/, .agents/skills/, .agents/subagents/), templates, and a configured .env file, run:

ant init
# or with language options (e.g., pt-br)
ant init --language pt-br

2. Prompt Script Batch Run (run)

To run a pre-written prompt from a markdown or text file in a single-shot execution:

ant run test_script.md
# you can pass any option (model, yolo, etc.) to it
ant run -y -m gemini-3.5-flash test_script.md

Environment Resolution and Default Values

The CLI resolves configuration by loading .env files. By default, it loads them in two stages:

  1. Physical CLI script installation folder: Loads .env for global default configuration.
  2. Current Working Directory (CWD): Loads .env for workspace-specific configurations (which override the global ones).

Alternatively, you can load a custom .env file using the --env-file / -e option. When a custom .env file is specified, the default .env files (global and CWD) are not loaded automatically, giving you full control over the variables.

If a .env file is not present or a specific variable is not set, the CLI falls back to the following default values:

Environment Variable CLI Option Description Default Value
GEMINI_API_KEY --api-key Gemini API Key None (Required)
GEMINI_MODEL --model / -m Gemini Model to be used gemini-3.1-flash-lite
ANTGRAVITY_LANG --language / -l CLI UI Language en-us
ANTGRAVITY_YOLO --yolo / -y Run in YOLO (Safe-bypass) Mode False (Safe Mode)
ANTGRAVITY_WORKSPACE --workspace / -w Restricted workspace paths None (Current CWD)
ANTGRAVITY_SYSTEM_INSTRUCTION --system-instruction / -s System instruction or path None
ANTGRAVITY_SKILLS_PATH --skills-path / -k Custom workspace skills folders None
ANTGRAVITY_SILENT --silent Hide thoughts and tool execution logs False
ANTGRAVITY_VERBOSE --verbose / -v Show internal reasoning details False
ANTGRAVITY_VERBOSE_SUBAGENTS --verbose-subagents Show internal reasoning details for subagents False

(You can always override these values dynamically by passing their respective flags on the command line).


How to Use

1. Single Prompt Mode

To send a prompt and receive the response directly:

ant "Write a greeting in Python"

2. Interactive Mode (REPL)

To start a continuous chat with the agent (which maintains session history):

ant

Useful commands in Interactive Mode:

  • /reset: Clears conversation history and resets agent context.
  • /exit or /quit: Closes the interactive terminal.
  • /help or ?: Displays a detailed help message with all commands, active skills, and subagents (including custom plugins).
  • /ants or /subagents: Lists all registered colony subagents and their capabilities.
  • /disable_skill <name>: Disables a global skill in the active session.
  • /enable_skill <name>: Re-enables a previously disabled global skill.
  • /disable_agent <name>: Disables a colony subagent (blocking delegation to it).
  • /enable_agent <name>: Re-enables a previously disabled colony subagent.
  • /reload: Reloads all active workspace skills, colony subagents, and clears caches.
  • /clear or /cls: Clears the terminal screen.
  • /history [count]: Displays recent prompt history.
  • /save <name>: Saves the active conversation step history to a JSON file (stored at <history_dir>/sessions/).
  • /load <name>: Restores step history from a previously saved JSON file.
  • /config: Displays active configuration parameters (with masked API key).

Auto-completion and Interactive Features:

  • Platform-Standard History Location: Command history is automatically saved to platform-compliant directory paths instead of user home cluttering:
    • Windows: %LOCALAPPDATA%\AntGravity\history
    • macOS: ~/Library/Application Support/AntGravity/history
    • Linux: ~/.local/share/antgravity/history
  • Active Agent Prompt Indicator: When a subagent is executing or was invoked, the prompt dynamically updates (e.g. You (-> SubagentName) > or Você (-> SubagentName) >) to show you the current agentic context.
  • Real-time Auto-completion: Typing / triggers commands/skills, @ triggers workspace files, and : lists colony subagents. Auto-completion features substring/middle-of-path matching, prefix prioritization, case-insensitivity, and backspace stability.
  • Smart Ellipsis for Skills: At REPL startup, active skills are listed in the welcome banner up to a limit of 5. Any excess skills are summarized with a localized ellipsis (... and more or ... e mais).
  • Multi-line Input Support: You can type multi-line prompts by ending a line with a backslash \. The CLI will automatically strip trailing whitespaces and continue reading input in the next line.
  • Stdin Pipe Support: You can run the CLI non-interactively using pipes (e.g., echo "Explain Python" | ant). The CLI will detect that stdin is redirected, read the prompt, and output the response without blocking.
  • Custom REPL Commands: You can extend the REPL by putting custom command scripts subclassing REPLCommand inside the .agents/commands/ folder of your workspace. They will be loaded dynamically at runtime.

3. Safe Mode vs YOLO Mode

  • Safe Mode (Default): Whenever the agent tries to run risky terminal commands (like the RUN_COMMAND tool), the CLI will request your permission in the console ([y/N]) before proceeding.
  • YOLO Mode (-y / --yolo): Disables all safety confirmations and executes all actions autonomously.
    ant -y "Create a folder named test and list the directory"
    

Available Options

You can customize the CLI behavior using flags:

Flag Shortcut Env Variable Description
--model -m GEMINI_MODEL Specifies the Gemini model (default: gemini-3.1-flash-lite).
--yolo -y ANTGRAVITY_YOLO Skips all permissions/confirmations and runs everything freely.
--workspace -w ANTGRAVITY_WORKSPACE Restricts file tools to a specific directory (can be repeated).
--system-instruction -s ANTGRAVITY_SYSTEM_INSTRUCTION Text with custom system instructions or path to a text file.
--api-key GEMINI_API_KEY Passes the API key directly on the command line.
--skills-path -k ANTGRAVITY_SKILLS_PATH Path to skills folders (can be repeated).
--silent ANTGRAVITY_SILENT Hides internal thoughts and tool calls in the terminal.
--verbose -v ANTGRAVITY_VERBOSE Displays the AI's internal reasoning thoughts in gray.
--verbose-subagents ANTGRAVITY_VERBOSE_SUBAGENTS Displays internal reasoning thoughts and tool execution logs for subagents, prefixed with [SubagentName].
--language -l ANTGRAVITY_LANG Specifies the output translation language (default: en-us).
--env-file -e Path to a custom .env file to load configurations from.
--version -V Displays the installed CLI version.

Localization (i18n)

The AntGravity CLI features built-in internationalization (i18n). Output messages, error states, and terminal prompts are decoupled from the source code and stored as JSON translation files inside the translate/ directory.

Structure of translate/

translate/
├── pt-br/                         # Brazilian Portuguese translations
│   ├── config.json
│   ├── console_io.json
│   ├── handlers.json
│   ├── parser.json
│   ├── repl.json
│   ├── runner.json
│   └── commands.json
└── en-us/                         # English translations (Default)
    ├── config.json
    ├── console_io.json
    ├── handlers.json
    ├── parser.json
    ├── repl.json
    ├── runner.json
    └── commands.json

Adding New Languages

To support a new language (e.g. es-es for Spanish):

  1. Create a new directory named after the locale code inside translate/ (e.g. translate/es-es/).
  2. Copy the JSON files from translate/en-us/ into the new folder and translate their text values.
  3. Switch the CLI runtime language using the --language es-es flag.

Customization and Settings (.agents)

The .agents folder at the root of your project is the Local Workspace Customization folder. Through it, you can define rules, create new skills, and customize agent responses.

Complete Structure of .agents

my-project/
└── .agents/
    ├── AGENTS.md                  # Project rules and guidelines
    ├── skills/                    # Folder containing specific skills
    │   └── my_custom_skill/       # Example of a skill
    │       ├── SKILL.md           # Skill instructions and triggers (Required)
    │       ├── scripts/           # Supporting scripts
    │       ├── examples/          # Usage/code examples
    │       └── references/        # Reference documentation
    └── subagents/                 # Colony subagents folder
        └── my_subagent/
            ├── AGENT.md           # Subagent manifesto and instructions
            └── scripts/           # Custom python/shell tools

1. Project Rules (AGENTS.md)

The .agents/AGENTS.md file defines the general rules of behavior, style, and technical constraints that the agent must follow in this project. Global rules can be set at C:\Users\<user>\.gemini\config\AGENTS.md for machine-wide application.

2. Skills (skills/)

Skills are packages of behavior dynamically loaded depending on context.

  • The SKILL.md file (Required): Defines name, description YAML frontmatter and the body with instructions.
  • Scripts (scripts/): Executable scripts inside are automatically exposed as tools (e.g., my_custom_skill.script_name).

3. Subagents (subagents/)

Subagents are specialized workers configured to execute isolated tasks under the parent agent's delegation.

  • The AGENT.md file (Required): Defines configuration frontmatter and system instructions. YAML parsing is powered by native Python PyYAML integration.
  • Custom Tools (scripts/): Scripts inside automatically register as subagent-exclusive tools.

Metadata

Release files for AntGravityCLI 1.2.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for AntGravityCLI 1.2.5
File Size Uploaded Provenance Actions
antgravitycli-1.2.5.tar.gz 50.3 kB Without provenance Details for antgravitycli-1.2.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for AntGravityCLI 1.2.5
File Interpreter ABI Platform Actions
antgravitycli-1.2.5-py3-none-any.whl Python 3 none any Details for antgravitycli-1.2.5-py3-none-any.whl

Total release size: 112.8 kB

Release files / antgravitycli-1.2.5.tar.gz

Download URL antgravitycli-1.2.5.tar.gz
Size 50.3 kB
Tags Source
SHA-256 checksum
How to use checksums
2f53247e39743ef56f1bdf446a75622e6112f8baef90c1f9c65c4abfcc27bd38
BLAKE2b-256 checksum
How to use checksums
ec66837adf8996779a3165b1f40e02b5f9912546d99404591b66a93d727b20a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Release files / antgravitycli-1.2.5-py3-none-any.whl

Download URL antgravitycli-1.2.5-py3-none-any.whl
Size 62.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ae1740c40acfc9ddb847c297fc37077aa79b87a08101f73c7956c76c414a955
BLAKE2b-256 checksum
How to use checksums
df426d46d581bd68cedd05b7121c9d099c7480b610d2cd117b7bab25ce9b87d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Security for AntGravityCLI 1.2.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page