> For the complete documentation index, see [llms.txt](https://asus-isg-aidc.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://asus-isg-aidc.gitbook.io/guide/latest/cli/commandreference/ai.md).

# AI Assistant

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/07/09    |

## Table of Contents

* [1. Overview](#overview)
* [2. Quick Start](#quick-start)
* [3. Subcommands](#subcommands)
  * [3.1 `ai chat`](#ai-chat)
  * [3.2 `ai model`](#ai-model)
  * [3.3 `ai skills`](#ai-skills)
  * [3.4 `ai config`](#ai-config)
  * [3.5 `ai ping`](#ai-ping)
* [4. Interactive Session](#interactive-session)
* [5. Slash Commands](#slash-commands)
* [6. Command Execution Loop](#command-execution-loop)
* [7. Skills](#skills)
* [8. Configuration Keys](#configuration-keys)
* [9. Migrating from `init ai-*`](#migrating)
* [10. Usage Examples](#usage-examples)
* [11. Quick Summary](#quick-summary)

***

## 1. Overview <a href="#overview" id="overview"></a>

The `ai` command group is a natural-language assistant for AIDC operations. Describe what you want in plain language (Traditional Chinese or English) and the assistant proposes the matching `aidc-cli` command(s), then offers to run each one **after you confirm**. It can read back the command output and continue advising, turning the CLI into a guided conversation instead of a list of flags to memorise.

```bash
aidc-cli ai <subcommand> [flags]
```

| Subcommand                | Purpose                                                      |
| ------------------------- | ------------------------------------------------------------ |
| [`ai chat`](#ai-chat)     | Chat with the assistant (interactive, or one-shot via `-q`). |
| [`ai model`](#ai-model)   | Pick or switch the active provider and model.                |
| [`ai skills`](#ai-skills) | Manage AI skills (list / enable / disable / show).           |
| [`ai config`](#ai-config) | Manage the AI configuration (show / set / path / check).     |
| [`ai ping`](#ai-ping)     | Check connectivity to the active AI provider.                |

{% hint style="info" %}
**First-run setup:** before the first chat, run [`aidc-cli ai model`](#ai-model) once to pick a provider (entering its API key when prompted) and a model. The assistant is a local command — it needs no inventory or BMC settings.
{% endhint %}

***

## 2. Quick Start <a href="#quick-start" id="quick-start"></a>

```bash
# 1. Pick a provider and model (guided; prompts for the API key when needed)
aidc-cli ai model

# 2. (Optional) verify configuration and connectivity
aidc-cli ai config check

# 3. Ask a one-shot question
aidc-cli ai chat -q "Check the BMC firmware version on Weka221"

# 4. Or start an interactive session
aidc-cli ai chat
```

***

## 3. Subcommands <a href="#subcommands" id="subcommands"></a>

### 3.1 `ai chat` — Talk to the Assistant <a href="#ai-chat" id="ai-chat"></a>

`aidc-cli ai chat` is the entry point for talking to the assistant. Without `-q` an interactive multi-turn session starts; with `-q "<prompt>"` the assistant runs a single turn, prints the result, and exits.

```bash
aidc-cli ai chat [flags]
```

| Flag         | Short |     Default     | Description                                                                         |
| ------------ | :---: | :-------------: | ----------------------------------------------------------------------------------- |
| `--query`    |  `-q` |        —        | One-shot prompt: run a single turn then exit. Omit to start an interactive session. |
| `--model`    |  `-m` |   active model  | Override the model for this invocation only (not saved to config).                  |
| `--skill`    |  `-s` |   active skill  | Skill to use for this session (overrides the active skill; `none` to disable).      |
| `--provider` |  `-p` | active provider | Override the active provider (type or custom endpoint name) for this session.       |
| `--system`   |   —   |        —        | Extra system prompt appended to the active skill.                                   |
| `--dry-run`  |   —   |     `false`     | Only suggest commands; do not offer to run them.                                    |
| `--debug`    |   —   |     `false`     | Trace request/response payloads to stderr, secrets masked.                          |
| `--timeout`  |   —   |       60s       | Override the overall request timeout for this session, e.g. `90s`, `2m`.            |

{% hint style="warning" %}
**Flag change:** `-q/--query` is the one-shot prompt. `-m/--model` now overrides the **model** for this invocation only — in older releases `-m` was the message flag. Update any saved scripts to `ai chat -q "..."`.
{% endhint %}

{% hint style="info" %}
`-p`/`-m` switch the provider/model for this invocation only; the on-disk active selection is unchanged. When `-p` switches to a different provider without `-m` and the kept model is not available there, a one-shot run stops with a clear error, while an interactive session starts with a note so you can fix it with `/model <id>`.
{% endhint %}

**Piped input** — when stdin is piped, its contents become the prompt (or are appended to `-q` as extra context), so the assistant can analyse logs or report files:

```bash
aidc-cli report show latest.json | aidc-cli ai chat -q "Summarise the key findings in this report"
```

### 3.2 `ai model` — Pick or Switch the Active Provider and Model <a href="#ai-model" id="ai-model"></a>

The single surface for choosing what the assistant talks to. With no argument it runs a guided picker; with a `<provider>/<model>` argument it performs a non-interactive direct switch (scriptable, no terminal needed).

```bash
# Guided picker: pick a provider, enter a key if needed, then pick a model
aidc-cli ai model

# Direct switch
aidc-cli ai model anthropic/claude-opus-4-8

# A custom endpoint name alone selects its fixed model
aidc-cli ai model "LAB Gemma"
```

The guided picker:

1. **Provider stage** — every known provider is listed with its state (`(active)`, `(configured)`, `(oauth)`, `(not set)`), followed by your saved custom endpoints. The list also offers **adding a custom endpoint** (name → base URL → model id → optional key) and **removing a saved provider**.
2. **Key prompt** — choosing a cloud provider with no saved key prompts for one inline. `copilot` accepts a blank key (it falls back to the `gh` CLI token).
3. **Model stage** — a cloud provider's live model list is fetched from the provider; `Enter a custom model name…` allows manual entry. When re-picking the same provider, `Skip (keep current)` keeps the current model.

A successful switch prints the new selection:

```
active: anthropic > claude-opus-4-8
```

{% hint style="info" %}
For a direct switch the provider must already be configured — add a key first with `aidc-cli ai config set <provider>.api_key <key>` or run the picker once. A model that is not in the provider's advertised list is applied with a warning rather than rejected.
{% endhint %}

### 3.3 `ai skills` — Manage AI Skills <a href="#ai-skills" id="ai-skills"></a>

```bash
aidc-cli ai skills list             # list skills; the active one is marked *
aidc-cli ai skills enable <name>    # set the active skill (persisted)
aidc-cli ai skills disable <name>   # clear the active skill
aidc-cli ai skills show <name>      # print a skill's metadata and system prompt
```

Example output of `ai skills list`:

```
=========================================
            Available AI Skills
=========================================
* aidc-ai-ops [builtin]
    Unified AIDC-CLI infrastructure skill for natural-language operations across
    deployment, hardware, networking, firmware, security, storage, and cluster workflows.
=========================================
Active skill: aidc-ai-ops  (* )
```

Example output of `ai skills enable aidc-ai-ops`:

```
active skill: aidc-ai-ops
```

### 3.4 `ai config` — Manage the AI Configuration <a href="#ai-config" id="ai-config"></a>

```bash
aidc-cli ai config show             # show the effective configuration, secrets masked
aidc-cli ai config set <key> <value> # edit one value by dotted key
aidc-cli ai config path             # print the absolute path of the AI config file
aidc-cli ai config check            # validate the active configuration and probe connectivity
```

#### `config show`

Prints the resolved configuration — active selection, every provider's state, custom endpoints, timeouts, and the config file path — masking secrets:

```
+-----------------------------------------------+
|             AIDC AI Configuration             |
+-----------------------------------------------+

◆ Active
  Provider:  anthropic
  Model:     claude-opus-4-8
  Skill:     aidc-ai-ops

◆ Providers
  openai       (not set)
  anthropic    ****nt99     endpoint URL: (default)
  google       (not set)
  xai          (not set)
  openrouter   (not set)
  copilot      (oauth, no key)

◆ Custom Endpoints
  LAB Gemma      google/gemma-4-26B           http://lab:8000/v1   key: (none)

◆ Timeouts
  Request:  1m0s (default)
  Idle:     1m0s (default)

◆ Paths
  Config:   /opt/aidc/ansible/vars/aidc/ai.yml

-------------------------------------------------
  aidc-cli ai model              # pick / switch model
  aidc-cli ai config set <key> <value> # edit a field
```

#### `config set`

Edits a single value by dotted key. Run it with no arguments to list every settable key:

```
Settable configuration keys:
  active.provider              active provider type or saved custom endpoint name
  active.model                 active model id
  active.skill                 active skill (use 'none' or empty to clear)
  <provider>.api_key           API key for a cloud provider, e.g. anthropic.api_key (creates it if unset)
  <provider>.base_url          base-URL override for a cloud provider (empty = provider default)
  custom."<name>".model_id     model id of a custom endpoint
  custom."<name>".base_url     base URL of a custom endpoint
  custom."<name>".api_key      optional API key of a custom endpoint
  timeout.request_seconds      per-request timeout in seconds (0 = default)
  timeout.idle_seconds         idle-stall timeout in seconds (0 = default)

Usage: aidc-cli ai config set <key> <value>
```

```bash
aidc-cli ai config set active.model claude-opus-4-8
aidc-cli ai config set active.provider anthropic
aidc-cli ai config set active.skill aidc-ai-ops           # 'none' clears it
aidc-cli ai config set anthropic.api_key sk-ant-...       # creates the provider if unset
aidc-cli ai config set openai.base_url https://api.openai.com/v1
aidc-cli ai config set custom."LAB Gemma".base_url http://lab:8000/v1
aidc-cli ai config set timeout.request_seconds 90
```

A successful set echoes the new value, masking secrets:

```
set anthropic.api_key = ****nt99
```

#### `config check`

Validates the active configuration, then probes connectivity — keeping config problems separate from connectivity problems. It exits non-zero on any failure, so it is usable in scripts:

```
=========================================
             AI Config Check
=========================================
Active : anthropic
Model  : claude-opus-4-8
Config : OK
Connectivity : OK (412ms)
=========================================
```

{% hint style="info" %}
A config file written by an older release (the grouped format) is reported as `Config : LEGACY` — re-run `aidc-cli ai model` to re-select your provider and model (re-enter keys if needed). Chat prints the same one-line warning until the config is re-saved.
{% endhint %}

### 3.5 `ai ping` — Check Provider Connectivity <a href="#ai-ping" id="ai-ping"></a>

Sends a minimal request to the active provider and reports the label, model, and round-trip latency — or the reason it failed. Useful right after configuring a provider.

```bash
aidc-cli ai ping
```

Example output (success):

```
=========================================
            AI Provider Ping
=========================================
Active : anthropic
Model  : claude-opus-4-8
Status : OK (412ms)
=========================================
```

Example output (failure):

```
=========================================
            AI Provider Ping
=========================================
Active : anthropic
Model  : claude-opus-4-8
Status : FAILED: invalid API key (401)
=========================================
```

***

## 4. Interactive Session <a href="#interactive-session" id="interactive-session"></a>

Running `aidc-cli ai chat` with no `-q` starts a multi-turn chat. A banner shows the active provider, model, mode, and skill:

```
AIDC AI  [anthropic / claude-opus-4-8]  (runs proposed commands after you confirm)
type "/help" for commands · Tab completes · Ctrl+C stops a reply · Ctrl+D or "exit" to quit
[skill] aidc-ai-ops
────────────────────────────────────────────────────────────

You: Check the BMC firmware version on Weka221

AI: I will run the following command:

    aidc-cli bmc bmc-ver --limit-hosts Weka221
```

* **Ctrl+C** cancels an in-flight reply and returns to the prompt (it does not exit).
* **Ctrl+D**, `exit`, or `quit` ends the session.
* Any line starting with `/` is a [slash command](#slash-commands) handled locally.

***

## 5. Slash Commands <a href="#slash-commands" id="slash-commands"></a>

Inside an interactive session, these commands are handled locally and never sent to the model. Type `/help` to see the list.

| Command                | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `/help`, `/?`          | Show the slash-command help.                                     |
| `/skills`              | List available skills.                                           |
| `/skill <name>`        | Switch skill for this session (`none` to disable).               |
| `/provider <provider>` | Switch provider or custom endpoint (e.g. `/provider anthropic`). |
| `/models`              | List models for the active provider.                             |
| `/model <id>`          | Switch the active model.                                         |
| `/config`              | Show the current (live session) AI config.                       |
| `/history`             | Show this session's conversation history.                        |
| `/exec [on\|off]`      | Toggle command execution (omit to flip).                         |
| `/sys`                 | Run `aidc-cli sysinfo` (read-only system diagnostics).           |
| `/clear`               | Clear the conversation history.                                  |
| `/exit`, `/quit`       | End the session.                                                 |

{% hint style="info" %}
`/provider` and `/model` change the selection **for this session only**; the on-disk active selection is unchanged. To persist a switch, use [`aidc-cli ai model`](#ai-model). When a provider switch keeps a model that the new provider does not serve, the session prints a note so you can fix it with `/model <id>` (list candidates with `/models`).
{% endhint %}

***

## 6. Command Execution Loop <a href="#command-execution-loop" id="command-execution-loop"></a>

When execution is enabled (the default — disable with `--dry-run` or `/exec off`), the assistant offers to run the `aidc-cli` commands it proposes:

```
────────────────────────────────────────────────────────────
detected 1 suggested command(s):
  [1] aidc-cli bmc bmc-ver --limit-hosts Weka221

▶ aidc-cli bmc bmc-ver --limit-hosts Weka221
Execute this command? [y/N]: y
running: aidc-cli bmc bmc-ver --limit-hosts Weka221
...
```

Key behaviours:

* **Every command needs a separate `[y/N]` confirmation.** Nothing runs without your explicit `y`.
* Commands run by **re-invoking `aidc-cli`**, so all existing guards still apply — license checks, per-command validation, and destructive-operation confirmations.
* The command's output is **fed back to the assistant** so it can interpret results and suggest the next step. This execute→analyse cycle is bounded to **5 rounds** to prevent runaway loops.
* Read-only `aidc-cli report show|list` commands run **automatically** (no `[y/N]`) so the assistant can read a freshly produced report without extra friction. If a command produces a new report file, that report is auto-read and fed back as well.

{% hint style="warning" %}
The assistant only ever proposes `aidc-cli` commands; non-`aidc-cli` lines are ignored and never executed. Destructive operations still prompt for their own confirmation when run.
{% endhint %}

***

## 7. Skills <a href="#skills" id="skills"></a>

A **skill** is a named instruction set (system prompt) that shapes how the assistant behaves. The built-in `aidc-ai-ops` skill teaches the assistant the full AIDC-CLI command surface so it can route natural-language requests to the right commands.

Skills are resolved in increasing priority so later sources override earlier ones with the same name:

1. **Built-in** skills shipped inside the binary (always available).
2. On-disk skills at the deployed skills path (editable in place without rebuilding).
3. Skills under the `AIDC_SKILLS_DIR` environment variable (highest priority; drop-in / overrides).

Set the active skill with `aidc-cli ai skills enable <name>` (clear it with `ai skills disable <name>`), or switch per-session with `aidc-cli ai chat --skill <name>` / `/skill <name>`.

***

## 8. Configuration Keys <a href="#configuration-keys" id="configuration-keys"></a>

The AI configuration is **flat**: one account per cloud provider type, plus named custom endpoints, plus a single active `provider / model / skill` selection. (Older releases grouped multiple accounts per provider — see [Migrating](#migrating).)

Everything is managed under `ai` itself:

| Command                                | Purpose                                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `aidc-cli ai model`                    | Pick/switch the active provider and model; add or remove providers and custom endpoints (guided). |
| `aidc-cli ai config show`              | Show the full configuration, secrets masked.                                                      |
| `aidc-cli ai config set <key> <value>` | Edit one field by dotted key (see [3.4](#ai-config) for the key list).                            |
| `aidc-cli ai config check`             | Validate config and probe connectivity (non-zero exit on failure).                                |

**Supported provider types:** `openai`, `anthropic`, `google`, `xai`, `openrouter`, `copilot`, plus named `custom` endpoints (local / self-hosted).

{% hint style="info" %}
`copilot` can fall back to the `gh` CLI token, so it works without a saved API key. All other cloud providers require one.
{% endhint %}

***

## 9. Migrating from `init ai-*` <a href="#migrating" id="migrating"></a>

The AI configuration commands moved from `init` to the `ai` group, and provider "groups" were removed in favour of the flat model above. Old command → new command:

| Old                                                       | New                                                |
| --------------------------------------------------------- | -------------------------------------------------- |
| `aidc-cli ai -m "..."`                                    | `aidc-cli ai chat -q "..."`                        |
| `aidc-cli ai models`                                      | `/models` inside a chat, or the `ai model` picker  |
| `aidc-cli ai config`                                      | `aidc-cli ai config show`                          |
| `aidc-cli ai skills`                                      | `aidc-cli ai skills list`                          |
| `aidc-cli init ai-get`                                    | `aidc-cli ai config show`                          |
| `aidc-cli init ai-set --interactive`                      | `aidc-cli ai model`                                |
| `aidc-cli init ai-set --provider X --group Y --api-key K` | `aidc-cli ai config set X.api_key K`               |
| `aidc-cli init ai-set --skill S`                          | `aidc-cli ai skills enable S`                      |
| `aidc-cli init ai-rm ...`                                 | `aidc-cli ai model` → `🗑 Remove a saved provider` |
| `aidc-cli init ai-models`                                 | `aidc-cli ai config show` (network-free)           |

{% hint style="warning" %}
A config file saved by an older release triggers a one-line legacy warning in `ai chat` and a `Config : LEGACY` verdict in `ai config check`. Re-run `aidc-cli ai model` once to re-select your provider and model (re-enter keys if needed).
{% endhint %}

***

## 10. Usage Examples <a href="#usage-examples" id="usage-examples"></a>

```bash
# One-shot question, let the assistant propose (and offer to run) commands
aidc-cli ai chat -q "Change the Link Type on Weka221 to Ethernet"

# One-shot, suggest only — never offer to run anything
aidc-cli ai chat --dry-run -q "How do I verify that the InfiniBand fabric is ready?"

# Use a specific provider and model just for this question
aidc-cli ai chat -p openai -m gpt-5 -q "summarise the latest hardware health report"

# Disable the skill and add a custom system instruction for this session
aidc-cli ai chat --skill none --system "Answer in English, be terse." -q "list bmc subcommands"

# Pipe a report into the assistant for analysis
aidc-cli report show hardware-health/CLI_chkhw_brief_2026-07-07_09-15-00.json | aidc-cli ai chat -q "Highlight all FAIL items in this report"

# Start an interactive session with a longer timeout
aidc-cli ai chat --timeout 2m

# Switch the active model non-interactively (e.g. in a setup script)
aidc-cli ai model anthropic/claude-opus-4-8

# Verify configuration and connectivity
aidc-cli ai config check
aidc-cli ai ping
```

***

## 11. Quick Summary <a href="#quick-summary" id="quick-summary"></a>

| Command                                      | Description                                                     |
| -------------------------------------------- | --------------------------------------------------------------- |
| `ai chat`                                    | Interactive session (one-shot via `-q`).                        |
| `ai model [<provider>/<model>]`              | Pick (guided) or switch (direct) the active provider and model. |
| `ai skills list`                             | List available AI skills.                                       |
| `ai skills enable <name>` / `disable <name>` | Set / clear the active skill.                                   |
| `ai skills show <name>`                      | Print a skill's metadata and system prompt.                     |
| `ai config show`                             | Show the effective AI configuration.                            |
| `ai config set <key> <value>`                | Edit one configuration value by dotted key.                     |
| `ai config path`                             | Print the AI config file path.                                  |
| `ai config check`                            | Validate config and probe connectivity.                         |
| `ai ping`                                    | Check connectivity to the active AI provider.                   |

**See also:** [Report](/guide/latest/cli/commandreference/report.md), [Initialization](/guide/latest/cli/commandreference/init.md).