agf CLI Reference

The agf command-line tool validates, lints, scaffolds, inspects, and visualizes Agent Format YAML files.

info

The agf CLI will be publicly available soon. Below is the command reference.

Commands

agf validate

Validate .agf.yaml files against the JSON Schema.

agf validate agent.agf.yaml
agf validate agents/          # recursive directory scan
agf validate --strict *.agf.yaml

Flag	Description
--strict	Treat unknown fields as errors (SEM-010)
--schema <file>	Use a custom JSON Schema file
--fail-on-warning	Exit 1 if any warnings

agf lint

Full validation pipeline: schema + 13 semantic rules + 9 lint rules.

agf lint agent.agf.yaml
agf lint --rules SEM-001,LINT-003 agent.agf.yaml
agf lint --severity warning agents/

Flag	Description
--rules <ids>	Run only specific rules
--exclude-rules <ids>	Skip specific rules
--severity <level>	Minimum severity: error, warning, info
--strict	Unknown fields become errors
--fail-on-warning	Exit 1 on warnings

agf init

Scaffold a new .agf.yaml from a built-in template.

agf init                              # default: minimal template
agf init --template react             # ReAct agent with tools
agf init --template pipeline          # Sequential pipeline
agf init --template enterprise        # Full governance
agf init --template remote            # Remote A2A agents
agf init --list                       # Show available templates
agf init -f my-agent.agf.yaml         # Custom output file

Flag	Description
-t, --template <name>	Template: minimal, react, pipeline, enterprise, remote
-f, --output <file>	Output file (default: agent.agf.yaml)
--id <id>	Pre-fill metadata.id
--name <name>	Pre-fill metadata.name
--list	List available templates
--force	Overwrite existing file

agf inspect

Parse and display a tree view of an agent definition.

agf inspect agent.agf.yaml
agf inspect --section action_space agent.agf.yaml
agf inspect --depth 2 agent.agf.yaml
agf inspect -o json agent.agf.yaml

Flag	Description
--depth <n>	Limit tree depth
--section <name>	Show only one section

agf graph

Render the agent dependency graph (follows local_agents file references).

agf graph orchestrator.agf.yaml
agf graph --format mermaid orchestrator.agf.yaml
agf graph --format dot orchestrator.agf.yaml | dot -Tpng -o graph.png

Flag	Description
--format <fmt>	ascii (default), mermaid, dot
--depth <n>	Max resolution depth (default: 10)

agf diff

Semantic diff between two .agf.yaml files. Arrays are matched by alias, not index.

agf diff v1.agf.yaml v2.agf.yaml
agf diff --section metadata v1.agf.yaml v2.agf.yaml
agf diff -o json v1.agf.yaml v2.agf.yaml

Flag	Description
--section <name>	Diff only a specific section

agf schema

Print the bundled JSON Schema.

agf schema                   # Pretty-printed
agf schema --compact         # Minified

agf version

Print CLI version, schema version, and schema $id URL.

agf version

Output Formats

All reporting commands support -o / --output:

Format	Description
text	Colored terminal output (default)
json	Machine-readable JSON
sarif	SARIF 2.1.0 for CI integration (GitHub Code Scanning)

Configuration File

Create .agf-cli.yaml in your project root:

output: text
strict: false
fail_on_warning: false
lint:
  exclude_rules: []
  severity: warning

CI/CD Integration

GitHub Actions

- name: Validate Agent Format
  run: |
    agf lint --fail-on-warning -o sarif agents/ > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/agent-format/agent-format-schema
    rev: v0.1.0
    hooks:
      - id: agf-lint
        files: '\.agf\.yaml$'