Automata CLI

0.4.0 verified Thu Apr 23 auth: no javascript

The `automata-cli` is a command-line interface tool designed to streamline Git and project management workflows by integrating with AI services. Its current stable version is 0.4.0, with a rapid release cadence, as evidenced by frequent minor and patch updates (e.g., v0.2.x, v0.3.x, v0.4.x) over a relatively short period, continuously adding new features and bug fixes. Key differentiators include an interactive configuration wizard, comprehensive GitFlow helpers such as `get-pr-info` for pull request details, `finish-feature` for branch cleanup, and `publish-release` for automated release sequences. It uniquely integrates with AI executors like Claude and Codex, allowing for automated tasks like finding, claiming, and implementing GitHub issues (`implement-next`), or executing AI prompts for code refactoring and fixes (`execute`, `execute-prompt`). The tool supports both GitHub (`gh CLI` integration) and Azure DevOps environments.

Common errors

error 'automata' is not recognized as an internal or external command, operable program or batch file. ↓

cause The `automata-cli` package is not installed globally or its executable path is not in your system's PATH.

fix

Run npm install -g automata-cli to install the CLI globally.

error Error: The gh CLI is required for GitHub operations. Please install it and ensure you are authenticated. ↓

cause The GitHub CLI (`gh`) is either not installed, not accessible in your system's PATH, or you are not authenticated with GitHub via `gh auth login`.

fix

Install gh (e.g., npm install -g @cli/cli or via system package manager) and run gh auth login to authenticate.

error Error: Configuration file not found at .../.automata/config.json. Please run 'automata config' to set up. ↓

cause The `automata` CLI cannot find its configuration file in the expected location (typically `.automata/config.json` in the current directory).

fix

Run automata config to launch the interactive wizard and create the configuration file.

error Error: You must provide a --with option (claude or codex). ↓

cause AI execution commands (`automata execute`, `automata execute-prompt`) require you to specify which AI model to use.

fix

Add the --with flag followed by claude or codex, e.g., automata execute --with claude --prompt "...".

Warnings

gotcha Many Git-related commands and `automata implement-next` require the `gh` CLI (GitHub CLI) to be installed and authenticated for GitHub operations. Without it, these commands will fail. ↓

fix Install and authenticate the `gh` CLI: `npm install -g @cli/cli` and then `gh auth login`.

gotcha This package is currently in major version 0 (e.g., `0.4.0`), indicating an unstable API. Breaking changes are likely to occur between minor versions (e.g., `0.3.x` to `0.4.x`) without adhering to strict semver for major version increments. Review changelogs carefully when upgrading. ↓

fix Pin exact versions in `package.json` or carefully review release notes before upgrading `0.x.x` versions.

gotcha AI commands (`implement-next`, `execute`, `execute-prompt`) interact with external AI models (Claude, Codex) and may incur costs or require specific API keys/configuration not detailed in basic usage. Ensure your environment is properly set up for AI service access. ↓

fix Consult the `automata-cli` documentation for details on configuring AI providers and managing API keys and costs.

gotcha The `automata` CLI saves its configuration to `.automata/config.json` in the current directory where the command is executed. Running the CLI from different directories may result in different configurations being used, or the need to re-run `automata config`. ↓

fix Run `automata config` from your project's root directory, or ensure the `.automata` directory with `config.json` is present and correctly configured in your working directory.

Install

npm install automata-cli

yarn add automata-cli

pnpm add automata-cli

Quickstart

Installs the CLI globally, launches the interactive configuration wizard, verifies installation, and demonstrates how to check PR information and preview AI-driven issue discovery.

# 1. Install the CLI globally
npm install -g automata-cli

# 2. Launch the interactive configuration wizard
#    Follow prompts to select your remote environment (e.g., GitHub 'gh' or Azure DevOps 'azdo')
automata config

# 3. Verify installation and explore available commands
automata --help

# 4. Example: Get information about the current Git branch's pull request (requires 'gh' CLI)
#    Ensure you are in a Git repository with an active branch pushed to a PR.
automata git get-pr-info

# 5. Example: Preview the next GitHub issue for AI implementation (requires 'gh' CLI and AI configuration)
automata implement-next --query-only

# 6. Example: Set config type non-interactively
automata config set type gh