CLI Reference

The Agent Actions CLI (agac) is your primary interface for building and running agentic workflows. Think of it like a conductor's baton for orchestrating LLM actions - you can execute workflows, inspect field dependencies, manage batch processing, and debug issues all from the command line.

Let's explore what agac can do for you.

Global Flags

These flags work with all commands and help you understand what's happening inside your agentic workflows:

--version

Display the Agent Actions version.

bash

BASH

agac --version

--debug

Enable debug mode with verbose logging and source file/line references.

bash

BASH

agac --debug run -a my_workflow

-v / --verbose

Enable verbose output.

bash

BASH

agac --verbose run -a my_workflow

-q / --quiet

Suppress non-essential output. Useful for scripts and CI/CD pipelines where you only want to see errors.

bash

BASH

agac --quiet run -a my_workflow

--help

Show help message and available commands.

bash

BASH

agac --help
agac run --help

Working Directory

You might wonder: do I need to be in my project's root directory to run commands?

No - Agent Actions CLI commands automatically detect your project root by searching for agent_actions.yml, similar to how git finds .git or npm finds package.json. This means you can run commands from any subdirectory within your project.

How It Works

The CLI walks up the directory tree from your current location looking for agent_actions.yml:

bash

BASH

my-project/
├── agent_actions.yml       # Project root marker
├── src/
│   ├── agents/
│   └── utils/
└── tests/

# All of these work the same:

# From project root
cd my-project
agac run -a my_workflow
# 📁 Project root: .

# From subdirectory
cd my-project/src/utils
agac run -a my_workflow
# 📁 Project root: ../..

# From any depth
cd my-project/src/agents/helpers
agac run -a my_workflow
# 📁 Project root: ../../../

Not in a Project?

If you're outside a project directory, you'll get a helpful error:

bash

BASH

$ cd /tmp
$ agac run -a my_workflow

Error: Not in an Agent Actions project

Could not find 'agent_actions.yml' in current directory or any parent directory.

Current directory: /tmp

Solutions:
  1. Navigate to your Agent Actions project directory
  2. Run 'agac init' to create a new project

Commands That Work Anywhere

These commands don't require being in a project:

• init - Create a new project
• --version - Show version
• --help - Display help

Commands Overview

Here's what each command does - organized by what you're trying to accomplish:

Running agentic workflows:

Command	Description
run	Execute an agentic workflow
batch	Manage batch processing operations

Inspecting and debugging:

Command	Description
inspect	Preflight + introspection — graph + validation with dependencies / action / context drill-downs
schema	Display input/output schemas and analyze field dependencies
preview	Preview data stored in the SQLite storage backend
dispositions	Inspect record-level processing dispositions per action
expect	Show the expectation rules each action would run, and report the verdicts a run stored
retry	Retry failed/exhausted records from a specific action forward
list-udfs	List discovered tools
validate-udfs	Validate tool references

Project management:

Command	Description
init	Initialize a new project
example	Browse and install example projects from GitHub
clean	Remove a workflow's working directories (output/staging opt-in)
docs	Generate documentation
status	Check agentic workflow status
skills	Install AI assistant skills (Claude Code / Codex)

Next Steps

• run Command - Execute agentic workflows with all available options
• batch Commands - Manage batch processing for large-scale operations
• preview Command - Inspect data in the SQLite storage backend
• Troubleshooting - Error messages and debugging strategies