CLI Reference

Overview

The agentmetal CLI is the primary command-line interface for managing infrastructure resources on the AgentMetal platform. It provides direct access to all resource types and supports both interactive and scriptable workflows.

Installation

Install the CLI using the official install script:

curl -fsSL https://get.agentmetal.dev/cli | sh

Or build from source:

git clone https://github.com/agentcloud/agentcloud.git
cd agentcloud
make build-cli
sudo mv bin/agentmetal /usr/local/bin/

Verify the installation:

agentmetal version

Authentication

The CLI requires an API key for all operations. You can provide credentials in two ways:

Global Flags

Flag	Description	Default
`--api-url`	Base URL of the AgentMetal API server	`http://localhost:8080`
`--api-key`	API key for authentication	(none)
`--output`	Output format: `json` or `table`	`table`

### Environment Variables

Variable	Description
`AGENTMETAL_API_URL`	Base URL of the AgentMetal API server
`AGENTMETAL_API_KEY`	API key for authentication

Environment variables are overridden by flags when both are set.

export AGENTMETAL_API_URL=http://localhost:8080
export AGENTMETAL_API_KEY=ak_live_abc123
agentmetal instance list

Available Subcommands

Subcommand	Description
`instance`	Manage compute instances (create, list, get, delete, ssh)
`database`	Manage managed databases (PostgreSQL, MySQL)
`vpc`	Manage Virtual Private Clouds
`subnet`	Manage subnets within VPCs
`security-group`	Manage security groups and firewall rules
`bucket`	Manage object storage buckets
`lb`	Manage load balancers (HTTP, TCP)
`dns`	Manage DNS zones and records
`k3s`	Manage lightweight Kubernetes clusters
`redis`	Manage Redis clusters
`queue`	Manage message queues (RabbitMQ, NATS)
`function`	Manage serverless functions
`iac`	Infrastructure as Code operations (validate, plan, apply, destroy)
`audit-log`	View audit logs for all operations

## Usage Pattern

All subcommands follow the same pattern:

agentmetal <resource> <operation> [flags]

Use --help on any subcommand for detailed usage:

agentmetal instance --help
agentmetal instance create --help

Output Formats

The --output flag controls how results are displayed:

# Table format (default, human-readable)
agentmetal instance list
JSON format (machine-readable, ideal for scripts)
agentmetal instance list --output json
Pipe JSON output to jq for filtering
agentmetal instance list --output json | jq '.[].id'