CLI Overview

Command-line interface for developing, testing, and deploying AI workflows locally and in production

Core Commands

  • agnt5 init - Scaffold new projects from templates
  • agnt5 dev - Local development server with hot-reload
  • agnt5 deploy - Push to production or staging environments
  • agnt5 logs - Stream logs from any environment
  • agnt5 config - Manage environment variables and settings

Installation

Verify Installation 

agnt5 --version

Quickstart 

# Initialize a new project
agnt5 init my-workflow

# Start development server
cd my-workflow
agnt5 dev

# Open http://localhost:3000

Upgrading

Commands Reference

$agnt5 dev

Start the local development server with live reload, built-in debugging, and real-time logs.

agnt5 dev [options]

Options:

  • --port <number> - Port to run the development server (default: 3000)
  • --host <string> - Host to bind the server (default: localhost)
  • --watch <pattern> - File patterns to watch for changes
  • --no-reload - Disable automatic reloading
  • --debug - Enable debug mode with verbose logging

Examples:

agnt5 dev
agnt5 dev --port 3001
agnt5 dev --watch "src/**/*"
agnt5 dev --debug

$agnt5 init

Initialize a new AGNT5 project with templates, configuration, and best practices.

agnt5 init <project-name> [options]

Options:

  • --template <name> - Project template (python, typescript, go, minimal)
  • --minimal - Create a minimal project structure
  • --no-install - Skip dependency installation
  • --git - Initialize git repository (default: true)

Examples:

agnt5 init my-project
agnt5 init my-ai-agent --template python
agnt5 init simple-workflow --minimal
agnt5 init my-project --no-install --no-git

agnt5 run

Execute workflows locally or remotely with comprehensive logging and error handling.

agnt5 run <workflow> [options]

Options:

  • --input <file> - Input data file (JSON)
  • --env <environment> - Target environment (local, dev, staging, prod)
  • --remote - Execute on remote AGNT5 runtime
  • --watch - Watch for file changes and re-run
  • --debug - Enable debug output

Examples:

agnt5 run my-workflow
agnt5 run data-processor --input data.json
agnt5 run my-workflow --remote --env staging
agnt5 run my-workflow --watch --debug

Deployment Commands

agnt5 deploy

Deploy your workflows to production with zero-downtime deployments and automatic scaling.

agnt5 deploy [options]

Options:

  • --env <environment> - Target environment (staging, production)
  • --watch - Watch deployment status
  • --no-build - Skip build step
  • --force - Force deployment even with warnings
  • --rollback - Rollback to previous deployment

Examples:

agnt5 deploy
agnt5 deploy --env staging
agnt5 deploy --watch --env production
agnt5 deploy --rollback

agnt5 build

Build your project for deployment.

agnt5 build [options]

Options:

  • --env <environment> - Build for specific environment
  • --output <directory> - Output directory (default: dist)
  • --minify - Minify output files
  • --sourcemap - Generate source maps

Examples:

agnt5 build
agnt5 build --env production --minify
agnt5 build --output ./build --sourcemap

Monitoring Commands

agnt5 logs

Stream real-time logs from your workflows with filtering, search, and export capabilities.

agnt5 logs [options]

Options:

  • --follow, -f - Follow log output in real-time
  • --filter <level> - Filter by log level (error, warn, info, debug)
  • --grep <pattern> - Filter logs by pattern
  • --tail <number> - Show last N lines (default: 100)
  • --env <environment> - Target environment
  • --export <file> - Export logs to file

Examples:

agnt5 logs
agnt5 logs --follow --filter error
agnt5 logs --grep "workflow-123" --tail 50
agnt5 logs --env production --export logs.json

agnt5 status

Check the status of your workflows, deployments, and system health across environments.

agnt5 status [options]

Options:

  • --env <environment> - Target environment
  • --watch, -w - Watch status in real-time
  • --json - Output in JSON format
  • --verbose - Show detailed status information

Examples:

agnt5 status
agnt5 status --env production --watch
agnt5 status --json --verbose

Configuration Commands

agnt5 config

Manage CLI configuration and settings.

agnt5 config <command> [options]

Subcommands:

  • get <key> - Get configuration value
  • set <key> <value> - Set configuration value
  • list - List all configuration values
  • reset - Reset configuration to defaults

Options:

  • --global - Modify global configuration
  • --env <environment> - Environment-specific config

Examples:

agnt5 config get api-key
agnt5 config set api-key your-api-key
agnt5 config set timeout 30000 --env production
agnt5 config list --global
agnt5 config reset

agnt5 auth

Manage authentication with AGNT5 services.

agnt5 auth <command>

Subcommands:

  • login - Authenticate with AGNT5
  • logout - Remove authentication
  • whoami - Show current user
  • token - Manage API tokens

Examples:

agnt5 auth login
agnt5 auth whoami
agnt5 auth logout

Environment Commands

agnt5 env

Manage deployment environments and their configuration.

agnt5 env <command> [options]

Subcommands:

  • list - List all environments
  • create <name> - Create new environment
  • delete <name> - Delete environment
  • set <key> <value> - Set environment variable
  • unset <key> - Remove environment variable

Examples:

agnt5 env list
agnt5 env create staging
agnt5 env set DATABASE_URL postgres://... --env staging
agnt5 env unset DEBUG --env production
agnt5 env delete old-staging

Utility Commands

agnt5 validate

Validate project configuration and workflow definitions.

agnt5 validate [file] [options]

Options:

  • --schema - Validate against specific schema
  • --fix - Attempt to fix validation errors
  • --strict - Use strict validation rules

Examples:

agnt5 validate
agnt5 validate workflow.yaml
agnt5 validate --strict --fix

agnt5 doctor

Diagnose common issues with your AGNT5 setup.

agnt5 doctor [options]

Options:

  • --verbose - Show detailed diagnostic information
  • --fix - Attempt to fix detected issues

Examples:

agnt5 doctor
agnt5 doctor --verbose --fix

Global Options

These options are available for all commands:

  • --help, -h - Show help information
  • --version, -v - Show CLI version
  • --verbose - Enable verbose output
  • --quiet, -q - Suppress non-error output
  • --config <file> - Use specific config file

Authentication Commands

Authentication is required before you can create projects, deploy, or interact with the Control Plane. Credentials are stored in ~/.agnt5/config.yaml and read on every invocation.

agnt5 auth login

Launches the authentication flow. By default the CLI requests a short-lived session ID from the Control Plane, opens your browser to the PropelAuth login screen, and polls until an API key is issued. The generated key is persisted to ~/.agnt5/config.yaml so subsequent commands can reuse it.

Syntax 

agnt5 auth login [options]

Options

Flag Description
--api-key <value> Skip the browser flow and provide an existing API key. The CLI validates the key by fetching the current user before saving it locally.

The CLI respects AGNT5_API_URL and other context settings when constructing the OAuth URLs, so ensure your context is correct before logging in. You can also provide AGNT5_API_KEY in the environment to bypass the login command entirely.

agnt5 auth logout

Clears any stored API keys and tokens from ~/.agnt5/config.yaml. You can re-authenticate later with agnt5 auth login.

Syntax 

agnt5 auth logout

agnt5 auth status

Displays whether you are authenticated, printing the email associated with the stored key along with the active environment and API base URL. If the saved key is invalid the command reports the failure and suggests agnt5 auth login.

Syntax 

agnt5 auth status

agnt5 whoami

Prints the email address tied to the stored credentials. This command is also available via agnt5 auth whoami and returns Not authenticated when no valid key is present.

Syntax 

agnt5 whoami

agnt5 version

Display CLI build metadata including version string, Go runtime, and platform. Use this command to inspect the CLI build information.

Syntax 

agnt5 version

Use agnt5 version paired with agnt5 whoami to confirm both your binary and credentials before deploying.

Development Server Commands

The agnt5 dev command group spins up a single Docker container that runs the Control Plane, Gateway, and worker coordinator required for local iteration. It mirrors the Vercel CLI vercel dev workflow: mount your project directory, watch for changes, and expose predictable ports.

All subcommands assume Docker is installed and that you have access to pull the agnt5/dev-server:latest image.

agnt5 dev up

Starts the development environment in the foreground by running docker run with a consistent container name (agnt5-dev-server). The command mounts the current working directory at /app, mounts .agnt5/db for observability storage.

Syntax 

agnt5 dev up [options]

Options

Flag Description
--runtime, -r Override runtime detection (valid values: python, node, go). By default the CLI infers the runtime from project files.
--service, -s Override the service name advertised inside the container. Defaults to the directory name.
--detach, -d Run the container in the background. Combine with agnt5 dev logs -f to tail logs.

Service Endpoints

  • HTTP Gateway: http://localhost:8090
  • gRPC Gateway: localhost:34190
  • MCP TCP server: localhost:8820

The CLI prevents duplicate containers by checking for an existing container named agnt5-dev-server and instructing you to stop it before recreating. When you request detached mode it prints follow-up commands so you can attach to logs or stop the server later.

agnt5 dev down

Stops the development container (docker stop agnt5-dev-server). If the container is not running the command prints an informational message instead of failing.

Syntax 

agnt5 dev down
Command
agnt5 dev down
Response
Stopping development server...
✓ Container agnt5-dev-server stopped
✓ Development environment shut down

Development server is offline.
Use 'agnt5 dev up' to restart.

agnt5 dev logs

Streams logs from the dev container via docker logs.

Syntax 

agnt5 dev logs [options]

Options

Flag Description
--follow, -f Follow log output (leave the stream open)

agnt5 dev status

Prints the current docker ps table entry for the dev container, then shows friendly endpoint hints if the container is running.

Syntax 

agnt5 dev status

Use status to verify port bindings without attaching to logs.

Clean Shutdown and State

The dev server writes observability data under .agnt5/db in your project. Deleting that directory resets the local SQLite database used for traces and metrics. To remove the container completely, run agnt5 dev down followed by docker rm agnt5-dev-server if it was created manually.

State Management

Location Purpose
.agnt5/db Local SQLite database for traces and metrics
agnt5-dev-server Docker container name used consistently
/app Mount point for your project directory inside container

Complete Cleanup 

# Stop and remove dev server
agnt5 dev down
docker rm agnt5-dev-server

# Reset observability data
rm -rf .agnt5/db

Project Management Commands

The agnt5 project command family helps you create Control Plane projects, sync local configuration, and explore existing projects. Many operations require an API key because they call the Control Plane directly.

agnt5 project create

Creates a new project remotely and, for Python projects, scaffolds a ready-to-run repository on disk. The command is also available as a top-level shortcut agnt5 create.

Syntax 

agnt5 project create [project-name] [options]
agnt5 create [project-name] [options]

Options

Flag Description
--organization-id Force the Control Plane organization to associate with the new project.

Flow Summary

  1. Prompt (or accept a CLI argument) for the project name
  2. Prompt for a language (python or typescript)
  3. Resolve the organization ID or prompt to choose
  4. Call the Control Plane to create the project
  5. Generate full project skeleton for Python projects
  6. Write .agnt5/project-ref for future CLI commands
  7. Print next steps

Python Project Scaffolding

For Python projects, the CLI generates:

  • app.py, src/<project>/functions.py
  • tests/__init__.py, tests/test_functions.py
  • pyproject.toml, agnt5.yaml, Dockerfile
  • .gitignore, README.md

Non-Python languages currently skip the scaffolding step but still create the remote project and update your local metadata.

agnt5 project list

Lists projects visible to your API key in a simple table. Pagination, search, and ordering options are available.

Syntax 

agnt5 project list [options]

Options

Flag Description
--page, -p Page number to request (default: 1)
--page-size Number of projects per page (default: 20)
--search, -s Filter by name, ref, or slug
--language, -l Filter by language (e.g., python)
--status Filter by status returned from the Control Plane
--order-by Sort column: created, updated, name (default: updated)
--order-dir Sort direction: asc or desc (default: desc)

The output includes truncated IDs, names, references, languages (with versions when available), statuses, and creation dates. Pagination metadata at the bottom shows how many results are displayed relative to the total.

agnt5 project info

Work in Progress

Placeholder command that will eventually print detailed metadata about the current project or a provided ID. For now it simply acknowledges the request. Use agnt5 project list to locate IDs until the implementation is complete.

Syntax 

agnt5 project info [project-id]

This command will eventually provide comprehensive project details including configuration, deployment status, environment variables, and resource usage metrics.

agnt5 project init

Work in Progress

Reserved for initializing an existing directory as an AGNT5 project. The command currently prints a stub message.

Syntax 

agnt5 project init

This command will eventually initialize an existing directory as an AGNT5 project by creating the necessary configuration files and project metadata.

Command
agnt5 project init
Response
Command acknowledged but not yet implemented.
Use 'agnt5 project create' to create new projects.

Local Project Metadata

Most project-aware commands rely on two files created during project create:

File Purpose
.agnt5/project-ref Binds the working directory to a Control Plane project reference
agnt5.yaml Holds language, environment, deploy, and variable configuration for the deployment pipeline

If you clone an existing project make sure both files are present (or run SaveProjectRef / SaveDeploymentProjectConfig helper functions) before using agnt5 deploy.

Project Reference File

The .agnt5/project-ref file contains the Control Plane project reference that links your local directory to the remote project. This file is automatically created during agnt5 project create and is required for deployment commands.

Deployment Configuration

The agnt5.yaml file contains project-specific configuration used by the deployment pipeline:

# Example agnt5.yaml structure
language: python
version: "3.12"
environment:
  development:
    # Development-specific config
  production:
    # Production-specific config
deploy:
  # Deployment configuration
variables:
  # Environment variables

Deployment Commands

agnt5 deploy is the all-in-one command that builds your project, pushes the resulting image to the configured registry, validates the target workspace, and creates (or updates) a deployment. It intentionally mirrors the Vercel CLI’s single entry point: run agnt5 deploy from the project root and the CLI orchestrates the rest.

Prerequisites

  • You must be authenticated (agnt5 auth login) so the CLI can talk to the Control Plane and container registries
  • The working directory needs a project binding via .agnt5/project-ref and a deployment manifest (agnt5.yaml). agnt5 project create scaffolds both for Python projects
  • Docker must be installed and running; the CLI performs connectivity checks and will error out with guidance if Docker or the registry cannot be reached

agnt5 deploy

The complete deployment workflow with build, push, and deployment orchestration.

Syntax 

agnt5 deploy [options]

Command Workflow

  1. Dry run (optional) – With --dry-run the CLI prints a deployment plan and exits without building or deploying
  2. Build – Creates a Docker context, optionally generates a Dockerfile for Python projects, and uses the local Docker daemon to build the image
  3. Push – Tags are pushed to the local registry by default, and optionally mirrored to a remote registry when --push-remote is set
  4. Deploy – The Control Plane client validates or creates the workspace, resumes it if paused, and issues a deployment request

Options

Common Options

Flag Description
--project-dir Use a different directory as the build context (default: .)
--environment Name of the deployment environment (default: development)
--prod Shorthand flag that forces environment to production
--staging Shorthand flag that forces environment to staging
--dry-run Show the plan without building or deploying
--build-only Stop after a successful build/push so you can deploy later

Build Options

Flag Description
--dockerfile Path to the Dockerfile (defaults to ./Dockerfile)
--no-cache Disable Docker layer caching
--clean-cache Prune Docker build cache before building
--pull Always attempt to pull newer base images
--platform Target platforms for multi-arch builds
--build-args Additional build arguments
--target Build a specific stage from multi-stage Dockerfile
--tags Append extra image tags

Registry Options

Flag Description
--push Push to local registry (default: true)
--push-remote Mirror to remote registry

Deployment Options

Flag Description
--replicas Number of replicas (default: 1)
--cpu CPU limit
--memory Memory limit

Build Stage Details

The build stage performs several safeguards before issuing a Docker build:

  • Validates Docker connectivity by pinging the daemon and pulling a tiny hello-world image to confirm registry access
  • Ensures Docker is installed, the project directory exists, and a Dockerfile is available (generating one for Python projects when needed)
  • Reads defaults from config.yaml/agnt5.yaml to name the image after your project reference and merges in any additional tags or build arguments you provided

If you set --clean-cache or --no-cache, the CLI prunes the Docker build cache before starting the build and forces base image pulls. Progress updates stream directly to the terminal (including the current Docker build step).

Registry Pushes

After a successful build, the CLI tags the image for the configured registry:

Local Registry

  • Local pushes go to localhost:5001 by default (or whatever deploy.registry.local_url resolves to)
  • Authentication uses your AGNT5 API key

Remote Registry

  • Remote pushes use deploy.registry.remote_url when defined; otherwise the CLI falls back to the default remote registry (iarun-agnt5-cr.protoml.dev)
  • Credentials come from config.yaml or, if omitted, reuse your API key
  • When both --push and --push-remote are enabled the CLI pushes to the local registry first, then mirrors the tag to the remote endpoint

You can opt out of pushing entirely with --push=false, but keep in mind that agnt5 deploy still expects to deploy the latest image tag.

Workspace Validation and Deployment

The deployment step uses the Control Plane API to ensure your workspace is ready:

Workspace States

State Action
No workspace CLI creates one automatically and waits (up to 10 minutes) for it to reach the ready phase
Paused Workspaces are resumed before deployment
Pending/Provisioning Triggers a wait loop until ready
Failed Produces actionable error messages and stops the deployment

Deployment Process

When the workspace is ready the CLI constructs a deployment payload with your image reference, replica count, and resource hints, then polls every five seconds (for up to five minutes) for the deployment to reach a running/ready status. Upon success it prints handy follow-up steps, including a curl example and a reminder to inspect logs via agnt5 logs.

Complete Example Workflow 

# 1. Check deployment plan
agnt5 deploy --prod --dry-run --replicas 3

# 2. Build and deploy to production
agnt5 deploy --prod --replicas 3 --cpu 1 --memory 1Gi --tags v1.2.0

# 3. Monitor deployment (see deployment visibility commands)
agnt5 list --environment production
agnt5 logs

Use --dry-run first to verify the deployment plan, then run the full command. Combine with agnt5 list and agnt5 logs to monitor the rollout.

Deployment Visibility Commands

Two top-level commands surface deployment information. They mirror Vercel’s vercel list and vercel logs, but the current implementation is still a work in progress. Expect behavior to evolve as the Control Plane endpoints mature.

Work in Progress

Both commands are currently under development. They return placeholder errors today but will provide full deployment visibility once the Control Plane endpoints are stabilized.

agnt5 list

Displays a list of deployments for the current project. The command accepts filters that will be wired to the Control Plane once the backing API stabilizes.

Syntax 

agnt5 list [options]
agnt5 ls [options]

Options

Flag Description
--environment Environment to inspect (default: development)
--limit Maximum number of deployments to show (default: 10)
--status Filter by deployment status
--all Include deployments from every environment

Current Status: Returns a placeholder error today (list functionality not yet implemented). Use the Control Plane UI or APIs directly for detailed history until the CLI integration ships.

agnt5 logs

Streams logs for a specific deployment. When an ID is omitted the command will eventually default to the latest deployment for the current project.

Syntax 

agnt5 logs [deployment-id] [options]

Options

Flag Description
--follow, -f Follow log output
--tail Number of lines to show from the end of the logs (default: 100)
--since Timestamp or duration filter (e.g., 2h, 30m)

Current Status: Returns a placeholder error until log streaming is implemented. The CLI currently surfaces a message reminding you that a deployment ID is required.

Planned Integration

Once these commands are complete they will work hand-in-hand with agnt5 deploy to provide an end-to-end workflow:

Example Future Workflow 

# 1. Deploy your project
agnt5 deploy --prod

# 2. List deployments to see the new one
agnt5 list --environment production

# 3. Monitor logs for the deployment
agnt5 logs deploy-abc123 --follow

# 4. Check deployment status
agnt5 list --status running

Integration with Deployment Pipeline

The visibility commands will integrate seamlessly with the deployment workflow:

  • Post-deployment monitoring: After agnt5 deploy completes, use agnt5 logs to monitor the new deployment
  • Historical analysis: Use agnt5 list to compare deployment performance over time
  • Debugging: Filter logs by time ranges to troubleshoot specific deployment issues
  • Multi-environment visibility: Compare deployments across development, staging, and production

Expected Features

When implementation is complete, expect:

  • Rich filtering: Filter deployments by status, environment, time range, and more
  • Real-time updates: Live log streaming with automatic reconnection
  • Deployment details: Full metadata about each deployment including build info, resource usage, and health status
  • Integration hooks: Commands will automatically detect the current project context and default to relevant deployments

Until these commands are implemented, you can monitor deployments through the Control Plane UI or use the direct APIs for programmatic access.

Context Switching Commands (Advanced)

Advanced users can switch between local development endpoints and hosted environments with the agnt5 context command group. Contexts influence which Control Plane and Gateway URLs the CLI uses, and they can also seed environment-specific configuration files.

Although the commands are marked hidden in --help, you can still run them directly. These are advanced commands primarily used for development and testing against different AGNT5 environments.

agnt5 context

Prints the currently active context (defaults to production when none is stored) along with the API base URL pulled from ~/.agnt5/context.yaml.

Syntax 

agnt5 context
Command
# Show current context
agnt5 context
Response
Current context: production
API URL: https://api.agnt5.com

agnt5 context list

Lists the built-in contexts (local, staging, production) and marks the active one with *.

Syntax 

agnt5 context list
Command
# List all available contexts
agnt5 context list
Response
Available contexts:

  local       http://localhost:34181
  staging     https://api.agnt5.xyz
* production  https://api.agnt5.com

agnt5 context set

Writes the chosen context to ~/.agnt5/context.yaml, updates related settings, and copies ~/.agnt5/config.<context>.yaml into config.yaml when present. The command also prints the final API and gateway URLs so you can confirm the change.

Syntax 

agnt5 context set <context>

Available Contexts

Context API URL Gateway URL Notes
local http://localhost:34181 http://localhost:34183 Dev stack with local OAuth
staging https://api.agnt5.xyz https://gw.agnt5.xyz Pre-production testing
production https://api.agnt5.com https://gw.agnt5.com Live environment (default)

Context Configuration

Every context also updates agnt5_env to a descriptive value (agnt5-local, agnt5-staging, agnt5-production). Commands like agnt5 auth login and agnt5 deploy pick up these values the next time they run, ensuring you are talking to the correct control plane.

Environment-Specific Configuration

Keep environment-specific credentials in ~/.agnt5/config.local.yaml, config.staging.yaml, etc. Switching contexts copies the relevant file over config.yaml, so your API keys stay in sync with the environment you just selected.

Configuration Files by Context

File Purpose
~/.agnt5/context.yaml Stores the currently active context
~/.agnt5/config.yaml Main configuration file, updated when contexts switch
~/.agnt5/config.local.yaml Local environment-specific settings
~/.agnt5/config.staging.yaml Staging environment-specific settings
~/.agnt5/config.production.yaml Production environment-specific settings

Context Workflow 

# 1. Check current context
agnt5 context

# 2. List available contexts
agnt5 context list

# 3. Switch to local development
agnt5 context set local

# 4. Authenticate against local environment
agnt5 auth login

# 5. Work with local dev stack
agnt5 dev up
agnt5 project list

# 6. Switch back to production
agnt5 context set production

Use Cases

Local Development

Switch to local context when working with the development stack:

agnt5 context set local
agnt5 dev up
agnt5 auth login

Staging Testing

Use staging context for pre-production testing:

agnt5 context set staging
agnt5 auth login
agnt5 deploy --staging

Production Operations

Default production context for live deployments:

agnt5 context set production
agnt5 auth login
agnt5 deploy --prod

Important: Always verify your context before performing sensitive operations like production deployments. Use agnt5 context to confirm you’re targeting the correct environment.

Configuration

Configuration

Configure the AGNT5 CLI for your development environment, API authentication, and deployment targets.

Project Configuration

The CLI uses a configuration file in your project root. The CLI supports both JavaScript and JSON formats:

agnt5.config.js 

module.exports = {
  // Project settings
  name: 'my-project',
  version: '1.0.0',
  description: 'My AI workflow project',

  // Development server
  dev: {
    port: 3000,
    host: 'localhost',
    watch: ['src/**/*', 'workflows/**/*'],
    reload: true,
    open: true
  },

  // Build settings
  build: {
    outDir: 'dist',
    minify: true,
    sourcemap: false,
    target: 'node16'
  },

  // Deployment settings
  deploy: {
    environment: 'production',
    region: 'us-east-1',
    timeout: 300000,
    retries: 3
  },

  // Workflow configuration
  workflows: {
    timeout: 60000,
    retries: 2,
    concurrency: 10
  }
};

agnt5.config.json 

{
  "name": "my-project",
  "version": "1.0.0",
  "dev": {
    "port": 3000,
    "host": "localhost",
    "watch": ["src/**/*"]
  },
  "deploy": {
    "environment": "production",
    "region": "us-east-1"
  }
}

Environment Variables

Configure the CLI using environment variables. These can be set in your shell or in a .env file:

Authentication 

# API authentication
AGNT5_API_KEY=your-api-key
AGNT5_BASE_URL=https://api.agnt5.com

# Alternative: use auth token
AGNT5_AUTH_TOKEN=your-jwt-token

Runtime Configuration 

# Default environment
AGNT5_ENVIRONMENT=development

# Logging
AGNT5_LOG_LEVEL=info  # error, warn, info, debug
AGNT5_LOG_FORMAT=pretty  # pretty, json

# Timeouts (in milliseconds)
AGNT5_TIMEOUT=30000
AGNT5_CONNECT_TIMEOUT=5000

# Development settings
AGNT5_DEV_PORT=3000
AGNT5_DEV_HOST=localhost
AGNT5_HOT_RELOAD=true

Deployment Configuration 

# Default deployment environment
AGNT5_DEPLOY_ENV=production

# Runtime settings
AGNT5_RUNTIME_REGION=us-east-1
AGNT5_RUNTIME_MEMORY=512
AGNT5_RUNTIME_TIMEOUT=300

Global CLI Configuration

Manage global CLI settings that persist across all projects:

View Current Configuration 

agnt5 config list --global

Set Global Configuration 

# API settings
agnt5 config set api-key your-api-key --global
agnt5 config set base-url https://api.agnt5.com --global

# Default preferences
agnt5 config set log-level info --global
agnt5 config set editor vscode --global
agnt5 config set auto-update true --global

Configuration File Location

Global configuration is stored in:

  • macOS/Linux: ~/.config/agnt5/config.json
  • Windows: %APPDATA%\agnt5\config.json

Environment-Specific Configuration

Configure different settings for different environments:

Development Environment 

agnt5 config set timeout 10000 --env development
agnt5 config set log-level debug --env development
agnt5 config set hot-reload true --env development

Staging Environment 

agnt5 config set base-url https://staging-api.agnt5.com --env staging
agnt5 config set timeout 30000 --env staging
agnt5 config set log-level info --env staging

Production Environment 

agnt5 config set base-url https://api.agnt5.com --env production
agnt5 config set timeout 60000 --env production
agnt5 config set log-level warn --env production

API Keys and Authentication

Setting Up API Keys

  1. Get your API key from the AGNT5 dashboard
  2. Set it globally for all projects: 
    agnt5 config set api-key your-api-key --global
  3. Or set per environment: 
    agnt5 config set api-key your-dev-key --env development
agnt5 config set api-key your-prod-key --env production

Using Environment Files

Create .env files for each environment:

.env.development

AGNT5_API_KEY=dev_api_key_here
AGNT5_BASE_URL=https://dev-api.agnt5.com
AGNT5_LOG_LEVEL=debug

.env.production

AGNT5_API_KEY=prod_api_key_here
AGNT5_BASE_URL=https://api.agnt5.com
AGNT5_LOG_LEVEL=warn

Authentication Methods

The CLI supports multiple authentication methods in order of precedence:

  1. Command-line flags: --api-key your-key
  2. Environment variables: AGNT5_API_KEY
  3. Project config file: agnt5.config.js
  4. Global config: ~/.config/agnt5/config.json
  5. Interactive login: agnt5 auth login

Configuration Validation

Validate your configuration to ensure everything is set up correctly:

# Validate current configuration
agnt5 config validate

# Validate specific environment
agnt5 config validate --env production

# Show configuration sources
agnt5 config validate --verbose

Configuration Schema

The complete configuration schema:

interface AgntConfig {
  // Project metadata
  name?: string;
  version?: string;
  description?: string;

  // API configuration
  apiKey?: string;
  baseUrl?: string;
  timeout?: number;

  // Development server
  dev?: {
    port?: number;
    host?: string;
    watch?: string[];
    reload?: boolean;
    open?: boolean;
  };

  // Build configuration
  build?: {
    outDir?: string;
    minify?: boolean;
    sourcemap?: boolean;
    target?: string;
  };

  // Deployment settings
  deploy?: {
    environment?: string;
    region?: string;
    timeout?: number;
    retries?: number;
  };

  // Workflow settings
  workflows?: {
    timeout?: number;
    retries?: number;
    concurrency?: number;
  };

  // Logging configuration
  logging?: {
    level?: 'error' | 'warn' | 'info' | 'debug';
    format?: 'pretty' | 'json';
  };
}

Best Practices

Security

  • Never commit API keys to version control
  • Use environment-specific keys for different deployment targets
  • Rotate keys regularly and update configuration
  • Use .env files for local development

Organization

  • Use project config files for team-shared settings
  • Use global config for personal preferences
  • Document environment variables in your project README
  • Validate configuration in CI/CD pipelines

Performance

  • Set appropriate timeouts for your use case
  • Configure concurrency limits based on your resources
  • Use region-specific endpoints for better latency
  • Enable caching where appropriate

Troubleshooting

Troubleshooting

Common issues and solutions when using the AGNT5 CLI.

Installation Issues

Command Not Found

Problem: agnt5: command not found after installation.

Solutions:

  1. Check if npm global packages are in PATH:

    npm config get prefix
echo $PATH

  2. Reinstall the CLI:

    npm uninstall -g agnt5
npm install -g agnt5

  3. Use npx as alternative:

    npx agnt5 --version

  4. Add npm global bin to PATH (if missing):

    # Add to ~/.bashrc or ~/.zshrc
export PATH=$PATH:$(npm config get prefix)/bin

Permission Denied

Problem: Permission errors during installation on macOS/Linux.

Solutions:

  1. Use a Node version manager (recommended):

    # Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
npm install -g agnt5

  2. Change npm’s default directory:

    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g agnt5

  3. Use sudo (not recommended):

    sudo npm install -g agnt5

Windows Installation Issues

Problem: Installation fails on Windows.

Solutions:

  1. Run as Administrator:

    • Right-click Command Prompt/PowerShell
    • Select “Run as Administrator”
    • Run installation command

  2. Use Windows Subsystem for Linux (WSL):

    wsl --install
# Then install in WSL environment

  3. Use Chocolatey:

    choco install nodejs
npm install -g agnt5

Authentication Issues

Invalid API Key

Problem: “Invalid API key” or “Unauthorized” errors.

Solutions:

  1. Verify your API key:

    agnt5 config get api-key

  2. Reset and re-enter API key:

    agnt5 config set api-key your-new-api-key

  3. Use interactive login:

    agnt5 auth login

  4. Check environment variables:

    echo $AGNT5_API_KEY

Token Expired

Problem: Authentication token has expired.

Solutions:

  1. Re-authenticate:

    agnt5 auth logout
agnt5 auth login

  2. Generate new API key from AGNT5 dashboard

  3. Update configuration:

    agnt5 config set api-key your-new-key

Development Server Issues

Port Already in Use

Problem: Development server fails to start due to port conflict.

Solutions:

  1. Use different port:

    agnt5 dev --port 3001

  2. Find what’s using the port:

    # macOS/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000

  3. Kill the process using the port:

    # macOS/Linux
kill -9 <PID>

# Windows
taskkill /PID <PID> /F

  4. Configure default port:

    agnt5 config set dev.port 3001

File Watching Issues

Problem: Hot reload not working or file changes not detected.

Solutions:

  1. Increase file watching limit (Linux):

    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

  2. Check watch patterns:

    agnt5 dev --watch "src/**/*" --debug

  3. Restart development server:

    # Stop server (Ctrl+C) and restart
agnt5 dev

  4. Use polling mode:

    agnt5 dev --poll

Deployment Issues

Deployment Timeout

Problem: Deployments fail due to timeout.

Solutions:

  1. Increase timeout:

    agnt5 deploy --timeout 600000  # 10 minutes

  2. Configure in project config:

    // agnt5.config.js
module.exports = {
  deploy: {
    timeout: 600000
  }
};

  3. Check deployment status:

    agnt5 status --env production --verbose

  4. Use incremental deployment:

    agnt5 deploy --incremental

Build Failures

Problem: Build process fails during deployment.

Solutions:

  1. Check build logs:

    agnt5 build --verbose

  2. Clean build cache:

    agnt5 build --clean

  3. Test build locally:

    agnt5 build --env production

  4. Check dependencies:

    npm audit
npm update

Network Issues

Connection Timeout

Problem: Commands fail with connection timeout.

Solutions:

  1. Check network connectivity:

    ping api.agnt5.com

  2. Increase timeout:

    agnt5 config set timeout 60000

  3. Configure proxy (if behind corporate firewall):

    npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

  4. Use different base URL:

    agnt5 config set base-url https://api-eu.agnt5.com

SSL Certificate Issues

Problem: SSL/TLS certificate errors.

Solutions:

  1. Update Node.js to latest stable version

  2. Use different registry (temporary):

    npm config set registry https://registry.npmjs.org/

  3. Disable SSL verification (not recommended for production):

    npm config set strict-ssl false

  4. Update CA certificates:

    # macOS
brew update && brew upgrade ca-certificates

# Ubuntu/Debian
sudo apt-get update && sudo apt-get upgrade ca-certificates

Performance Issues

Slow Commands

Problem: CLI commands are running slowly.

Solutions:

  1. Enable caching:

    agnt5 config set cache.enabled true

  2. Increase concurrency:

    agnt5 config set concurrency 20

  3. Use local runtime for development:

    agnt5 run workflow --local

  4. Profile command execution:

    agnt5 --verbose --profile run workflow

Memory Issues

Problem: CLI process uses too much memory.

Solutions:

  1. Increase Node.js memory limit:

    export NODE_OPTIONS="--max-old-space-size=4096"
agnt5 command

  2. Reduce concurrency:

    agnt5 config set workflows.concurrency 5

  3. Clear cache:

    agnt5 cache clear

Configuration Issues

Configuration Not Loading

Problem: CLI ignores configuration files.

Solutions:

  1. Verify config file location:

    agnt5 config validate --verbose

  2. Check config file syntax:

    node -c agnt5.config.js

  3. Use explicit config file:

    agnt5 --config ./my-config.js command

  4. Reset configuration:

    agnt5 config reset

Getting Help

Enable Debug Mode

For detailed troubleshooting information:

agnt5 --debug command
agnt5 --verbose command

Check System Information 

agnt5 doctor --verbose

Validate Setup 

agnt5 config validate
agnt5 auth whoami
agnt5 status --verbose

Contact Support

If you’re still experiencing issues:

  1. Check the logs:

    agnt5 logs --level error --tail 100

  2. Create a minimal reproduction case

  3. Include system information:

    agnt5 --version
node --version
npm --version
echo $AGNT5_API_KEY | cut -c1-8  # First 8 chars only

  4. Report the issue with full error messages and steps to reproduce