> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
# AGNT5 CLI Reference

## CLI Overview


**Binary**: `agnt5`
**Install (macOS)**: `brew install agnt5/tap/agnt5`
**Install (Linux)**: `curl -LsSf https://agnt5.com/cli.sh | bash`
**Core commands**: `agnt5 init`, `agnt5 deploy`, `agnt5 logs`, `agnt5 config`, `agnt5 auth`, `agnt5 project`
**Config home**: `~/.agnt5/` (credentials, context)


## Core Commands

- `agnt5 init` - Scaffold new projects from templates
- `agnt5 deploy` - Push to production or staging environments
- `agnt5 logs` - Stream logs from any environment
- `agnt5 config` - Manage environment variables and settings

## Installation

<Tabs defaultValue="homebrew">
  <TabsList>
    <TabsTrigger value="homebrew">macOS</TabsTrigger>
    <TabsTrigger value="curl">Linux</TabsTrigger>
  </TabsList>

  <TabsContent value="homebrew">
    Install the CLI using Homebrew:

    ```bash
    brew install agnt5/tap/agnt5
    ```

  </TabsContent>

  <TabsContent value="curl">
    Install using the install script:

    ```bash
    curl -LsSf https://agnt5.com/cli.sh | bash
    ```

    <Callout type="warning">
    **Configure your PATH**

    Add the CLI to your PATH after installation:

    ```bash
    echo 'export PATH="$HOME/.agnt5/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    ```

    Use `~/.zshrc` if you're using zsh instead of bash.
    </Callout>

  </TabsContent>
</Tabs>

### Verify Installation

```bash
agnt5 --version
```

## Quickstart

```bash
# Initialize a new project
agnt5 init my-workflow
cd my-workflow

# Authenticate and deploy
agnt5 auth login
agnt5 deploy
```

## Upgrading

<Tabs defaultValue="homebrew">
  <TabsList>
    <TabsTrigger value="homebrew">Homebrew</TabsTrigger>
    <TabsTrigger value="cli">CLI</TabsTrigger>
  </TabsList>

{" "}

<TabsContent value="homebrew">
    ```bash
    brew upgrade agnt5
    ```
  </TabsContent>

  <TabsContent value="cli">
    ```bash
    agnt5 upgrade
    ```
  </TabsContent>
</Tabs>


## Commands Reference


**Top-level commands**: `agnt5 init`, `agnt5 run`, `agnt5 deploy`, `agnt5 logs`, `agnt5 config`, `agnt5 auth`, `agnt5 project`, `agnt5 context`, `agnt5 list`
**Invocation shape**: `agnt5 <command> [args] [options]`
**Help**: `agnt5 --help` for top-level; `agnt5 <command> --help` per subcommand


### `agnt5 init`

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

```bash
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:**
```bash
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.

```bash
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:**
```bash
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.

```bash
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:**
```bash
agnt5 deploy
agnt5 deploy --env staging
agnt5 deploy --watch --env production
agnt5 deploy --rollback
```

### `agnt5 build`

Build your project for deployment.

```bash
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:**
```bash
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.

```bash
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:**
```bash
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.

```bash
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:**
```bash
agnt5 status
agnt5 status --env production --watch
agnt5 status --json --verbose
```

## Configuration Commands

### `agnt5 config`

Manage CLI configuration and settings.

```bash
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:**
```bash
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.

```bash
agnt5 auth <command>
```

**Subcommands:**
- `login` - Authenticate with AGNT5
- `logout` - Remove authentication
- `whoami` - Show current user
- `token` - Manage API tokens

**Examples:**
```bash
agnt5 auth login
agnt5 auth whoami
agnt5 auth logout
```

## Environment Commands

### `agnt5 env`

Manage deployment environments and their configuration.

```bash
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:**
```bash
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.

```bash
agnt5 validate [file] [options]
```

**Options:**
- `--schema` - Validate against specific schema
- `--fix` - Attempt to fix validation errors
- `--strict` - Use strict validation rules

**Examples:**
```bash
agnt5 validate
agnt5 validate workflow.yaml
agnt5 validate --strict --fix
```

### `agnt5 doctor`

Diagnose common issues with your AGNT5 setup.

```bash
agnt5 doctor [options]
```

**Options:**
- `--verbose` - Show detailed diagnostic information
- `--fix` - Attempt to fix detected issues

**Examples:**
```bash
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.


**Commands**: `agnt5 auth login [--api-key <value>]`, `agnt5 auth logout`, `agnt5 auth whoami`
**Credential store**: `~/.agnt5/config.yaml` (persisted on login, read on every invocation)
**Env overrides**: `AGNT5_API_KEY` bypasses the login command; `AGNT5_API_URL` overrides the Control Plane URL
**Auth flow**: browser-based OAuth via PropelAuth; CLI polls the Control Plane until an API key is issued


### `agnt5 auth login`

<CommandLayout command="auth login">
  <div slot="documentation">
    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
    ```bash
    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. |

    <Callout type="info">
    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.
    </Callout>
  </div>

  <div slot="examples">
    <Tabs defaultValue="oauth">
      <TabsList>
        <TabsTrigger value="oauth">OAuth flow</TabsTrigger>
        <TabsTrigger value="apikey">With API key</TabsTrigger>
        <TabsTrigger value="success">Success response</TabsTrigger>
      </TabsList>

      <TabsContent value="oauth">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth login
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting authentication flow...
          ✓ Session ID requested from Control Plane

          Opening browser for authentication...
          → https://auth.agnt5.com/propelauth/login

          Waiting for authentication to complete...
          ✓ Authentication successful
          ✓ API key saved to ~/.agnt5/config.yaml

          You are now authenticated as: user@example.com
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="apikey">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth login --api-key agnt5_sk_abc123...
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Validating provided API key...
          ✓ API key is valid
          ✓ User verified: user@example.com
          ✓ API key saved to ~/.agnt5/config.yaml

          Authentication complete.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="success">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth login
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Already authenticated as: user@example.com
          ✓ API key is valid and active

          Current context: production
          API URL: https://api.agnt5.com

          No action needed.
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 auth logout`

<CommandLayout command="auth logout">
  <div slot="documentation">
    Clears any stored API keys and tokens from `~/.agnt5/config.yaml`. You can re-authenticate later with `agnt5 auth login`.

    ### Syntax
    ```bash
    agnt5 auth logout
    ```
  </div>

  <div slot="examples">
    <Tabs defaultValue="basic">
      <TabsList>
        <TabsTrigger value="basic">Logout</TabsTrigger>
        <TabsTrigger value="already">Already logged out</TabsTrigger>
      </TabsList>

      <TabsContent value="basic">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth logout
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ API key cleared from ~/.agnt5/config.yaml
          ✓ Authentication tokens removed

          You have been logged out successfully.
          Use 'agnt5 auth login' to authenticate again.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="already">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth logout
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          No authentication credentials found.
          Already logged out.
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 auth status`

<CommandLayout command="auth status">
  <div slot="documentation">
    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
    ```bash
    agnt5 auth status
    ```
  </div>

  <div slot="examples">
    <Tabs defaultValue="authenticated">
      <TabsList>
        <TabsTrigger value="authenticated">Authenticated</TabsTrigger>
        <TabsTrigger value="invalid">Invalid key</TabsTrigger>
        <TabsTrigger value="notauth">Not authenticated</TabsTrigger>
      </TabsList>

      <TabsContent value="authenticated">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth status
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Authenticated as: user@example.com
          ✓ API key is valid

          Environment: production
          API URL: https://api.agnt5.com
          Context: production

          Authentication status: Active
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="invalid">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth status
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✗ Authentication failed
          ✗ Stored API key is invalid or expired

          Please run 'agnt5 auth login' to re-authenticate.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="notauth">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 auth status
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✗ Not authenticated

          No API key found in ~/.agnt5/config.yaml
          Run 'agnt5 auth login' to authenticate.
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 whoami`

<CommandLayout command="whoami">
  <div slot="documentation">
    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
    ```bash
    agnt5 whoami
    ```
  </div>

  <div slot="examples">
    <Tabs defaultValue="authenticated">
      <TabsList>
        <TabsTrigger value="authenticated">Authenticated</TabsTrigger>
        <TabsTrigger value="notauth">Not authenticated</TabsTrigger>
      </TabsList>

      <TabsContent value="authenticated">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 whoami
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          user@example.com
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="notauth">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 whoami
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Not authenticated
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 version`

<CommandLayout command="version">
  <div slot="documentation">
    Display CLI build metadata including version string, Go runtime, and platform. Use this command to inspect the CLI build information.

    ### Syntax
    ```bash
    agnt5 version
    ```

    <Callout type="info">
    Use `agnt5 version` paired with `agnt5 whoami` to confirm both your binary and credentials before deploying.
    </Callout>
  </div>

  <div slot="examples">
    <Tabs defaultValue="version">
      <TabsList>
        <TabsTrigger value="version">Version info</TabsTrigger>
        <TabsTrigger value="combined">With whoami</TabsTrigger>
      </TabsList>

      <TabsContent value="version">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 version
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          AGNT5 CLI v1.2.3

          Build Information:
            Version: 1.2.3
            Go version: go1.21.0
            Platform: darwin/amd64
            Build date: 2024-01-15 10:30:45
            Git commit: abc1234
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="combined">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 version && agnt5 whoami
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          AGNT5 CLI v1.2.3

          Build Information:
            Version: 1.2.3
            Go version: go1.21.0
            Platform: darwin/amd64
            Build date: 2024-01-15 10:30:45
            Git commit: abc1234

          user@example.com
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>


## 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.


**Commands**: `agnt5 project create [name] [--organization-id <id>]` (alias `agnt5 create`); other `agnt5 project` subcommands manage existing projects
**Languages supported**: `python`, `typescript`
**Required**: API key (`agnt5 auth login` first)
**Side effects**: creates project in Control Plane; for Python projects scaffolds `app.py`, `src/<project>/functions.py`, etc.; writes `.agnt5/project-ref` for subsequent CLI calls


### `agnt5 project create`

<CommandLayout command="project create">
  <div slot="documentation">
    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
    ```bash
    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`

    <Callout type="info">
    Non-Python languages currently skip the scaffolding step but still create the remote project and update your local metadata.
    </Callout>
  </div>

  <div slot="examples">
    <Tabs defaultValue="interactive">
      <TabsList>
        <TabsTrigger value="interactive">Interactive create</TabsTrigger>
        <TabsTrigger value="python">Python project</TabsTrigger>
        <TabsTrigger value="withorg">With organization</TabsTrigger>
      </TabsList>

      <TabsContent value="interactive">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project create
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ? Project name: my-ai-workflow
          ? Select language:
            ❯ python
              typescript
          ? Python version: 3.12

          ? Select organization:
            ❯ Acme Corp (org-abc123)
              Personal (org-def456)

          Creating project...
          ✓ Project created successfully

          Project Details:
            ID: proj-xyz789
            Name: my-ai-workflow
            Slug: my-ai-workflow
            Reference: acme/my-ai-workflow
            Status: active

          Next steps:
            cd my-ai-workflow
            pip install -r requirements.txt
            agnt5 deploy
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="python">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 create python-workflow
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Creating project 'python-workflow'...
          ? Select language: python
          ? Python version: 3.12
          ? Organization: Acme Corp (org-abc123)

          ✓ Project created in Control Plane
          ✓ Generating Python project structure...

          Generated files:
            ✓ app.py
            ✓ src/python_workflow/__init__.py
            ✓ src/python_workflow/functions.py
            ✓ tests/test_functions.py
            ✓ pyproject.toml
            ✓ agnt5.yaml
            ✓ Dockerfile
            ✓ .gitignore
            ✓ README.md

          ✓ .agnt5/project-ref created

          Project ready! Next steps:
            cd python-workflow
            pip install -e .
            agnt5 deploy
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="withorg">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 create my-project --organization-id org-abc123
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Creating project 'my-project'...
          Using organization: org-abc123

          ? Select language:
            ❯ python
              typescript

          ✓ Project created successfully

          Project Details:
            ID: proj-123456
            Organization: org-abc123
            Reference: acme/my-project

          Project directory created with Python scaffolding.
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 project list`

<CommandLayout command="project list">
  <div slot="documentation">
    Lists projects visible to your API key in a simple table. Pagination, search, and ordering options are available.

    ### Syntax
    ```bash
    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.
  </div>

  <div slot="examples">
    <Tabs defaultValue="basic">
      <TabsList>
        <TabsTrigger value="basic">Basic list</TabsTrigger>
        <TabsTrigger value="search">Search & filter</TabsTrigger>
        <TabsTrigger value="pagination">Pagination</TabsTrigger>
      </TabsList>

      <TabsContent value="basic">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project list
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Projects (showing 3 of 3 total):

          ID        | Name             | Reference           | Language | Status  | Updated
          ----------|------------------|---------------------|----------|---------|----------
          proj-abc  | my-ai-workflow   | acme/my-ai-workflow | python   | active  | 2 days ago
          proj-def  | data-processor   | acme/data-processor | python   | active  | 1 week ago
          proj-ghi  | api-service      | acme/api-service    | node     | paused  | 2 weeks ago

          Page 1 of 1 (3 projects total)
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="search">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project list --search "workflow" --language python
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Projects matching 'workflow' (language: python):

          ID        | Name             | Reference           | Language | Status  | Updated
          ----------|------------------|---------------------|----------|---------|----------
          proj-abc  | my-ai-workflow   | acme/my-ai-workflow | python   | active  | 2 days ago
          proj-xyz  | batch-workflow   | acme/batch-workflow | python   | active  | 5 days ago

          Page 1 of 1 (2 projects found, 2 total)
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="pagination">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project list --page 2 --page-size 10 --order-by created --order-dir asc
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Projects (page 2, ordered by created date):

          ID        | Name             | Reference           | Language | Status  | Created
          ----------|------------------|---------------------|----------|---------|----------
          proj-klm  | analytics-api    | acme/analytics-api  | python   | active  | Jan 15
          proj-nop  | webhook-handler  | acme/webhook-handler| node     | active  | Jan 18
          proj-qrs  | ml-pipeline      | acme/ml-pipeline    | python   | active  | Jan 20

          Page 2 of 5 (30 projects total, showing 11-20)
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 project info`

<CommandLayout command="project info">
  <div slot="documentation">
    <Callout type="warning">
    **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.
    </Callout>

    ### Syntax
    ```bash
    agnt5 project info [project-id]
    ```

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

  <div slot="examples">
    <Tabs defaultValue="current">
      <TabsList>
        <TabsTrigger value="current">Current project</TabsTrigger>
        <TabsTrigger value="specific">Specific project</TabsTrigger>
      </TabsList>

      <TabsContent value="current">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project info
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Command acknowledged but not yet implemented.
          Use 'agnt5 project list' to view available projects.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="specific">
        <ExampleBlock title="Command" variant="command">
          ```bash
          agnt5 project info proj-123
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Command acknowledged but not yet implemented.
          Use 'agnt5 project list' to view available projects.
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 project init`

<CommandLayout command="project init">
  <div slot="documentation">
    <Callout type="warning">
    **Work in Progress**

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

    ### Syntax
    ```bash
    agnt5 project init
    ```

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

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      agnt5 project init
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Command acknowledged but not yet implemented.
      Use 'agnt5 project create' to create new projects.
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

## 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 |

<Callout type="tip">
If you clone an existing project make sure both files are present (or run `SaveProjectRef` / `SaveDeploymentProjectConfig` helper functions) before using `agnt5 deploy`.
</Callout>

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

```yaml
# 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.


**Command**: `agnt5 deploy [options]`
**Required**: authenticated session (`agnt5 auth login`); project binding (`.agnt5/project-ref`); deployment manifest (`agnt5.yaml`); running Docker daemon
**Key flags**: `--environment`, `--prod`, `--staging`, `--dry-run`, `--build-only`, `--platform`, `--replicas`, `--cpu`, `--memory`, `--push-remote`
**Side effects**: builds Docker image; pushes to local registry (and remote if `--push-remote`); creates/updates Control Plane deployment
**Stages**: dry-run plan (optional) → build → push → deploy


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

<CommandLayout command="deploy">
  <div slot="documentation">
    The complete deployment workflow with build, push, and deployment orchestration.

    ### Syntax
    ```bash
    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 |
  </div>

  <div slot="examples">
    <Tabs defaultValue="basic">
      <TabsList>
        <TabsTrigger value="basic">Basic deployment</TabsTrigger>
        <TabsTrigger value="build">Build customization</TabsTrigger>
        <TabsTrigger value="production">Production</TabsTrigger>
        <TabsTrigger value="dryrun">Dry run</TabsTrigger>
      </TabsList>

      <TabsContent value="basic">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Deploy to development environment
          agnt5 deploy
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting deployment...
          ✓ Docker connectivity check passed
          ✓ Project reference found: acme/my-project
          ✓ Building image: localhost:5001/acme/my-project:latest

          Building Docker image...
          [+] Building 45.2s (12/12) FINISHED
          ✓ Image built successfully

          ✓ Pushing to local registry
          ✓ Validating workspace (development)
          ✓ Deploying to workspace

          Deployment successful!

          Next steps:
            curl http://localhost:8090/call -d '{"serviceName":"my-project"}'
            agnt5 logs
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Deploy to staging
          agnt5 deploy --staging
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="build">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Clean build without cache
          agnt5 deploy --clean-cache
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting deployment with clean cache...
          ✓ Pruning Docker build cache
          ✓ Pulling fresh base images

          Building Docker image...
          [+] Building 120.5s (12/12) FINISHED
          ✓ Clean build completed
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Multi-platform build
          agnt5 deploy --platform linux/amd64,linux/arm64
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Build only (no deployment)
          agnt5 deploy --build-only
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="production">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Full production deployment
          agnt5 deploy --prod --replicas 3 --cpu 1 --memory 1Gi --tags v1.2.0
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Starting production deployment...
          ✓ Environment: production
          ✓ Replicas: 3
          ✓ Resources: 1 CPU, 1Gi memory
          ✓ Additional tags: v1.2.0

          Building Docker image...
          [+] Building 52.1s (12/12) FINISHED
          ✓ Image tagged: v1.2.0

          ✓ Pushing to local registry
          ✓ Mirroring to remote registry
          ✓ Validating production workspace
          ✓ Deploying with 3 replicas

          Production deployment successful!

          Deployment ID: dep-prod-abc123
          Status: running (3/3 replicas ready)
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="dryrun">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # See deployment plan
          agnt5 deploy --dry-run
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Deployment Plan (DRY RUN):

          Project: acme/my-project
          Environment: development
          Image: localhost:5001/acme/my-project:latest
          Replicas: 1
          Resources: default

          Build Steps:
          1. Validate Docker connectivity
          2. Build image from ./Dockerfile
          3. Push to localhost:5001

          Deploy Steps:
          1. Validate/create development workspace
          2. Deploy with 1 replica
          3. Wait for ready status

          No changes will be made (dry run mode).
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Plan production deployment
          agnt5 deploy --prod --dry-run --replicas 3
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

## 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

<Callout type="info">
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).
</Callout>

## 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

<Callout type="warning">
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.
</Callout>

## 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

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

<Callout type="tip">
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.
</Callout>


**Programmatic equivalents**: the CLI calls Control Plane HTTP endpoints — see [API reference](/api-reference/create-contact.md) for the request shapes





## 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.


**Commands**: `agnt5 list [--environment <env>] [--limit <n>] [--status <s>] [--all]` (alias `agnt5 ls`); `agnt5 logs [options]`
**Status**: work-in-progress; both commands return a placeholder error today (`list functionality not yet implemented`) — use the Control Plane UI/API directly until the integration ships
**Inspection alternatives**: query the Control Plane HTTP API or browse Studio


<Callout type="warning">
**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.
</Callout>

### `agnt5 list`

<CommandLayout command="list">
  <div slot="documentation">
    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
    ```bash
    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 |

    <Callout type="info">
    **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.
    </Callout>
  </div>

  <div slot="examples">
    <Tabs defaultValue="basic">
      <TabsList>
        <TabsTrigger value="basic">Basic listing</TabsTrigger>
        <TabsTrigger value="filtered">Filtered results</TabsTrigger>
        <TabsTrigger value="environments">Environment-specific</TabsTrigger>
      </TabsList>

      <TabsContent value="basic">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # List recent deployments
          agnt5 list
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: list functionality not yet implemented

          Use the Control Plane UI for deployment history.
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Short alias
          agnt5 ls
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="filtered">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Filter by status
          agnt5 list --status running --limit 20
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: list functionality not yet implemented

          Expected output:
          ID          | Status  | Environment | Created    | Image
          ------------|---------|-------------|------------|-------
          dep-abc123  | running | production  | 2 min ago  | v1.2.0
          dep-def456  | running | staging     | 1 hr ago   | v1.1.8
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # List all deployments across environments
          agnt5 list --all
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="environments">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show production deployments
          agnt5 list --environment production
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: list functionality not yet implemented

          Expected output for production:
          ID          | Status  | Created    | Image  | Replicas
          ------------|---------|------------|--------|----------
          dep-prod-01 | running | 2 min ago  | v1.2.0 | 3/3
          dep-prod-02 | stopped | 1 hr ago   | v1.1.9 | 0/3
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

### `agnt5 logs`

<CommandLayout command="logs">
  <div slot="documentation">
    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
    ```bash
    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`) |

    <Callout type="info">
    **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.
    </Callout>
  </div>

  <div slot="examples">
    <Tabs defaultValue="basic">
      <TabsList>
        <TabsTrigger value="basic">Basic logs</TabsTrigger>
        <TabsTrigger value="streaming">Live streaming</TabsTrigger>
        <TabsTrigger value="filtered">Time filtering</TabsTrigger>
      </TabsList>

      <TabsContent value="basic">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show logs for latest deployment
          agnt5 logs
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: deployment ID required

          Log streaming not yet implemented.
          Use the Control Plane UI for deployment logs.
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show last 50 lines from recent logs
          agnt5 logs --tail 50
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="streaming">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Stream logs for specific deployment
          agnt5 logs deploy-abc123 --follow
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: deployment ID required

          Expected behavior:
          2024-01-15T10:30:45Z [INFO] Starting service...
          2024-01-15T10:30:46Z [INFO] Handler registered: greet_user
          2024-01-15T10:30:47Z [INFO] Service ready on port 8080
          2024-01-15T10:30:48Z [INFO] Received request: greet_user
          ... (streaming continues)
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Follow logs with short flag
          agnt5 logs deploy-abc123 -f
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="filtered">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Show logs from last 2 hours
          agnt5 logs --since 2h
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          Error: deployment ID required

          Expected filtered output:
          2024-01-15T08:30:45Z [INFO] Service healthy
          2024-01-15T08:35:12Z [INFO] Request processed
          2024-01-15T09:15:33Z [WARN] High memory usage
          2024-01-15T09:45:21Z [INFO] Memory usage normal
          ```
        </ExampleBlock>

        <ExampleBlock title="Command" variant="command">
          ```bash
          # Follow logs with time filter
          agnt5 logs deploy-abc123 -f --since 30m
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

## 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

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

<Callout type="tip">
Until these commands are implemented, you can monitor deployments through the Control Plane UI or use the direct APIs for programmatic access.
</Callout>


## 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.


**Commands**: `agnt5 context` (show current), `agnt5 context use <name>`, `agnt5 context list`
**Context store**: `~/.agnt5/context.yaml`
**Default context**: `production` (API URL `https://api.agnt5.com`)
**Hidden from `--help`**: yes, but invokable directly


<Callout type="info">
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.
</Callout>

### `agnt5 context`

<CommandLayout command="context">
  <div slot="documentation">
    Prints the currently active context (defaults to `production` when none is stored) along with the API base URL pulled from `~/.agnt5/context.yaml`.

    ### Syntax
    ```bash
    agnt5 context
    ```
  </div>

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      # Show current context
      agnt5 context
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Current context: production
      API URL: https://api.agnt5.com
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

### `agnt5 context list`

<CommandLayout command="context list">
  <div slot="documentation">
    Lists the built-in contexts (`local`, `staging`, `production`) and marks the active one with `*`.

    ### Syntax
    ```bash
    agnt5 context list
    ```
  </div>

  <div slot="examples">
    <ExampleBlock title="Command" variant="command">
      ```bash
      # List all available contexts
      agnt5 context list
      ```
    </ExampleBlock>

    <ExampleBlock title="Response" variant="response">
      ```
      Available contexts:

        local       http://localhost:34181
        staging     https://api.agnt5.xyz
      * production  https://api.agnt5.com
      ```
    </ExampleBlock>
  </div>
</CommandLayout>

### `agnt5 context set`

<CommandLayout command="context set">
  <div slot="documentation">
    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
    ```bash
    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) |
  </div>

  <div slot="examples">
    <Tabs defaultValue="local">
      <TabsList>
        <TabsTrigger value="local">Local development</TabsTrigger>
        <TabsTrigger value="staging">Staging</TabsTrigger>
        <TabsTrigger value="production">Production</TabsTrigger>
      </TabsList>

      <TabsContent value="local">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch to local development
          agnt5 context set local
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: local
          ✓ Configuration copied from config.local.yaml

          Active endpoints:
            API URL: http://localhost:34181
            Gateway: http://localhost:34183
            gRPC Gateway: localhost:34184
            Auth URL: https://86934364.propelauthtest.com

          You are now targeting the local development stack.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="staging">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch to staging environment
          agnt5 context set staging
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: staging
          ✓ Configuration copied from config.staging.yaml

          Active endpoints:
            API URL: https://api.agnt5.xyz
            Gateway: https://gw.agnt5.xyz
            Auth URL: https://auth.agnt5.xyz/propelauth

          You are now targeting the staging environment.
          ```
        </ExampleBlock>
      </TabsContent>

      <TabsContent value="production">
        <ExampleBlock title="Command" variant="command">
          ```bash
          # Switch back to production
          agnt5 context set production
          ```
        </ExampleBlock>

        <ExampleBlock title="Response" variant="response">
          ```
          ✓ Context switched to: production
          ✓ Configuration copied from config.production.yaml

          Active endpoints:
            API URL: https://api.agnt5.com
            Gateway: https://gw.agnt5.com
            Auth URL: https://auth.agnt5.com/propelauth

          You are now targeting the production environment.
          ```
        </ExampleBlock>
      </TabsContent>
    </Tabs>
  </div>
</CommandLayout>

## 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

<Callout type="tip">
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.
</Callout>

### 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

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

```bash
agnt5 context set local
agnt5 auth login
```

### Staging Testing
Use `staging` context for pre-production testing:

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

### Production Operations
Default `production` context for live deployments:

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

<Callout type="warning">
**Important:** Always verify your context before performing sensitive operations like production deployments. Use `agnt5 context` to confirm you're targeting the correct environment.
</Callout>


## Configuration

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


## Troubleshooting

Common issues and solutions when using the AGNT5 CLI.


**Diagnostic commands**: `agnt5 --version`, `agnt5 auth whoami`, `agnt5 context`
**Common failure modes**: missing CLI on PATH (`command not found`); missing/expired credentials; Docker daemon unreachable; wrong context for the target environment
**Reset paths**: re-run `agnt5 auth login` to refresh credentials; `agnt5 context use <name>` to switch environment; reinstall via the platform's install method to fix PATH issues


## Installation Issues

### Command Not Found

**Problem**: `agnt5: command not found` after installation.

**Solutions**:
1. **Check if npm global packages are in PATH**:
   ```bash
   npm config get prefix
   echo $PATH
   ```

2. **Reinstall the CLI**:
   ```bash
   npm uninstall -g agnt5
   npm install -g agnt5
   ```

3. **Use npx as alternative**:
   ```bash
   npx agnt5 --version
   ```

4. **Add npm global bin to PATH** (if missing):
   ```bash
   # 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):
   ```bash
   # 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**:
   ```bash
   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):
   ```bash
   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)**:
   ```bash
   wsl --install
   # Then install in WSL environment
   ```

3. **Use Chocolatey**:
   ```bash
   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**:
   ```bash
   agnt5 config get api-key
   ```

2. **Reset and re-enter API key**:
   ```bash
   agnt5 config set api-key your-new-api-key
   ```

3. **Use interactive login**:
   ```bash
   agnt5 auth login
   ```

4. **Check environment variables**:
   ```bash
   echo $AGNT5_API_KEY
   ```

### Token Expired

**Problem**: Authentication token has expired.

**Solutions**:
1. **Re-authenticate**:
   ```bash
   agnt5 auth logout
   agnt5 auth login
   ```

2. **Generate new API key** from AGNT5 dashboard

3. **Update configuration**:
   ```bash
   agnt5 config set api-key your-new-key
   ```

## Deployment Issues

### Deployment Timeout

**Problem**: Deployments fail due to timeout.

**Solutions**:
1. **Increase timeout**:
   ```bash
   agnt5 deploy --timeout 600000  # 10 minutes
   ```

2. **Configure in project config**:
   ```javascript
   // agnt5.config.js
   module.exports = {
     deploy: {
       timeout: 600000
     }
   };
   ```

3. **Check deployment status**:
   ```bash
   agnt5 status --env production --verbose
   ```

4. **Use incremental deployment**:
   ```bash
   agnt5 deploy --incremental
   ```

### Build Failures

**Problem**: Build process fails during deployment.

**Solutions**:
1. **Check build logs**:
   ```bash
   agnt5 build --verbose
   ```

2. **Clean build cache**:
   ```bash
   agnt5 build --clean
   ```

3. **Test build locally**:
   ```bash
   agnt5 build --env production
   ```

4. **Check dependencies**:
   ```bash
   npm audit
   npm update
   ```

## Network Issues

### Connection Timeout

**Problem**: Commands fail with connection timeout.

**Solutions**:
1. **Check network connectivity**:
   ```bash
   ping api.agnt5.com
   ```

2. **Increase timeout**:
   ```bash
   agnt5 config set timeout 60000
   ```

3. **Configure proxy** (if behind corporate firewall):
   ```bash
   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080
   ```

4. **Use different base URL**:
   ```bash
   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):
   ```bash
   npm config set registry https://registry.npmjs.org/
   ```

3. **Disable SSL verification** (not recommended for production):
   ```bash
   npm config set strict-ssl false
   ```

4. **Update CA certificates**:
   ```bash
   # 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**:
   ```bash
   agnt5 config set cache.enabled true
   ```

2. **Increase concurrency**:
   ```bash
   agnt5 config set concurrency 20
   ```

3. **Use local runtime** for development:
   ```bash
   agnt5 run workflow --local
   ```

4. **Profile command execution**:
   ```bash
   agnt5 --verbose --profile run workflow
   ```

### Memory Issues

**Problem**: CLI process uses too much memory.

**Solutions**:
1. **Increase Node.js memory limit**:
   ```bash
   export NODE_OPTIONS="--max-old-space-size=4096"
   agnt5 command
   ```

2. **Reduce concurrency**:
   ```bash
   agnt5 config set workflows.concurrency 5
   ```

3. **Clear cache**:
   ```bash
   agnt5 cache clear
   ```

## Configuration Issues

### Configuration Not Loading

**Problem**: CLI ignores configuration files.

**Solutions**:
1. **Verify config file location**:
   ```bash
   agnt5 config validate --verbose
   ```

2. **Check config file syntax**:
   ```bash
   node -c agnt5.config.js
   ```

3. **Use explicit config file**:
   ```bash
   agnt5 --config ./my-config.js command
   ```

4. **Reset configuration**:
   ```bash
   agnt5 config reset
   ```

## Getting Help

### Enable Debug Mode

For detailed troubleshooting information:

```bash
agnt5 --debug command
agnt5 --verbose command
```

### Check System Information

```bash
agnt5 doctor --verbose
```

### Validate Setup

```bash
agnt5 config validate
agnt5 auth whoami
agnt5 status --verbose
```

### Contact Support

If you're still experiencing issues:

1. **Check the logs**:
   ```bash
   agnt5 logs --level error --tail 100
   ```

2. **Create a minimal reproduction case**

3. **Include system information**:
   ```bash
   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