> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-05-13
title: Configuration
category: CLI
description: Configure the AGNT5 CLI for your development environment and deployment targets
hideRightSidebar: true
---

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


**Config file locations**: project root (`agnt5.config.js`, `agnt5.config.json`, or `agnt5.yaml`); user home (`~/.agnt5/config.yaml` for credentials, `~/.agnt5/context.yaml` for environment)
**Config formats**: JavaScript (`agnt5.config.js`) or JSON (`agnt5.config.json`); manifests use YAML (`agnt5.yaml`)
**Precedence**: CLI flags > env vars (`AGNT5_*`) > project config > user config > built-in defaults


## Project Configuration

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

### `agnt5.config.js`

```javascript
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`

```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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
agnt5 config list --global
```

### Set Global Configuration
```bash
# 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
```bash
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
```bash
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
```bash
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:
   ```bash
   agnt5 config set api-key your-api-key --global
   ```
3. **Or set per environment:**
   ```bash
   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`
```bash
AGNT5_API_KEY=dev_api_key_here
AGNT5_BASE_URL=https://dev-api.agnt5.com
AGNT5_LOG_LEVEL=debug
```

#### `.env.production`
```bash
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:

```bash
# 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:

```typescript
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