The DeployHQ CLI includes a local AI assistant for deployment help and integrations for AI coding agents like Claude Code and OpenAI Codex.

## AI Assistant (dhq assist)

Get AI-powered help for your deployments using a local LLM. All data stays on your machine -- nothing is sent to external AI services.

If you are already using an AI coding agent like Claude Code, Codex, or Cursor, your agent can interact with DeployHQ directly through the CLI and API -- you do not need `dhq assist`. The local assistant is best suited for developers who want a privacy-first, offline-capable option without relying on an external coding agent. It uses an open-source model via [Ollama](https://ollama.com) and keeps all data on your machine.

### Setup

The assistant requires [Ollama](https://ollama.com) running locally. Run the one-time setup:

```bash
dhq assist --setup
```

This installs Ollama (if needed) and downloads the default model (`qwen2.5:3b`, approximately 2GB).

### Asking Questions

```bash
# Ask about a deployment
dhq assist "why did my deploy fail?" -p my-app

# Get suggestions
dhq assist "what should I do?" -p my-app

# Ask about DeployHQ concepts
dhq assist "what does transfer_files do?"
```

The assistant automatically gathers context from your project (recent deployments, server configuration, logs) to provide relevant answers.

### Interactive Mode

For a conversational experience:

```bash
dhq assist --interactive -p my-app
```

### Checking Status

Verify that Ollama is running and the model is available:

```bash
dhq assist --status
```

### Using a Different Model

```bash
dhq assist "why did my deploy fail?" --model llama3.2
```

## Installing the DeployHQ Skill for AI Agents

The CLI can install a DeployHQ "skill" into the AI coding agents on your machine so they can discover and drive `dhq` commands directly. Supported agents include Claude Code, Cursor, OpenAI Codex, and Windsurf.

### Listing Supported Agents

```bash
dhq skills list
```

This shows every supported AI agent and whether the DeployHQ skill is already installed.

### Installing the Skill

```bash
# Install for all detected user-scope agents (Claude Code, Cursor, etc.)
dhq skills install
```

By default, this installs for the user-scope agents detected on your machine. Project-scope agents (such as GitHub Copilot) are skipped so that running the command never silently modifies the current repository.

To install for a specific agent -- including a project-scope one -- pass `--agent`:

```bash
# Install for a specific agent by name
dhq skills install --agent claude-code

# Install for a project-scope agent (writes into the current repository)
dhq skills install --agent copilot
```

`dhq hello` runs `dhq skills install` as part of guided onboarding, so in most cases you never need to run it separately.

### Deprecated: dhq setup

Earlier versions used `dhq setup <agent>` (for example `dhq setup claude`) to install per-agent plugins one at a time. That command still works but is **deprecated** -- prefer `dhq skills install`, which detects your installed agents automatically.

```bash
# Deprecated -- use "dhq skills install" instead
dhq setup claude
```

## Command Catalog

The CLI exposes a full command catalog as JSON, designed for AI agent discovery:

```bash
dhq commands --json
```

This outputs every command, subcommand, flag, and description in a structured format that agents can parse to understand available operations.

### Agent-Optimized Help

```bash
dhq --help --agent
```

This outputs help in JSON format optimized for machine consumption.

## Agent Identification

When running the CLI from an automation agent, set the `DEPLOYHQ_AGENT` environment variable to identify the agent:

```bash
DEPLOYHQ_AGENT=my-bot dhq deploy -p my-app --json
```

The CLI also automatically detects common agent environments:
- `DEPLOYHQ_AGENT` environment variable
- `CLAUDE_CODE` or `CLAUDECODE` environment variable (Claude Code)
- `CURSOR_AGENT` environment variable (Cursor)
- `WINDSURF_AGENT` environment variable (Windsurf)
- Standard CI environment variables (GitHub Actions, GitLab CI, etc.)

## MCP Server

The CLI includes a built-in MCP (Model Context Protocol) server that enables AI assistants like Claude Desktop to interact with DeployHQ:

```bash
dhq mcp
```

This starts the MCP server in stdio mode. For detailed setup and usage instructions, see the [MCP Server](https://www.deployhq.com/support/mcp-server) documentation.

## Showing Resources by URL

Resolve a DeployHQ URL to structured data:

```bash
dhq show https://mycompany.deployhq.com/projects/my-app
```

This is useful for AI agents that encounter DeployHQ URLs in conversations or documents.