> 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/gettingstarted.md). # Getting Started | Developer | Last modified | | --------- | ------------- | | AIDC Team | 2026/07/06 | ## Table of Contents * [1. Before You Begin](#before-you-begin) * [2. The Configure-First Workflow](#configure-first-workflow) * [3. Stage 1 — Initial Setup](#stage-1-initial-setup) * [4. Stage 2 — OS Deployment](#stage-2-os-deployment) * [5. Stage 3 — System Configuration](#stage-3-system-configuration) * [6. Stage 4 — Network and Drivers](#stage-4-network-and-drivers) * [7. Stage 5 — Firmware Baseline (Optional)](#stage-5-firmware-baseline) * [8. Stage 6 — Services and Storage](#stage-6-services-and-storage) * [9. Stage 7 — Validate and Create a Golden Baseline](#stage-7-validate-and-baseline) * [10. Day-2 Operations](#day-2-operations) * [11. Common Patterns](#common-patterns) * [12. Next Steps](#next-steps) *** ## 1. Before You Begin Make sure the following are ready before starting: | Requirement | Details | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | AIDC-CLI installed | See [Installation & Setup](/guide/latest/installation.md) for VM provisioning | | License key | Provided by ASUS; required before any command works | | Node CSV filled in | Node hostnames, OS IPs, BMC IPs, and groups — see [Installation § Node Database](/guide/latest/installation.md) | | BMC network reachable | The AIDC Server must reach every node's BMC IP | | OS images available | ISO images for the target OS, discoverable by `init image-discovery` | {% hint style="info" %} Every command supports `--help`. When unsure about a flag, run `aidc-cli --help` first. {% endhint %} *** ## 2. The Configure-First Workflow AIDC-CLI separates **configuration** from **execution**: 1. **Configure once** with [`aidc-cli init ...-set`](/guide/latest/cli/commandreference/init.md) — settings are saved on the AIDC Server. 2. **Execute anywhere** with the operational commands (`deploy`, `bmc`, `fwupdate`, `slurm`, …) — they read the saved settings automatically. Most execution commands fail or behave unexpectedly when their `init` settings are missing. Each command page shows a yellow **Prerequisite** box listing exactly which `init` steps it needs — if you see one, complete those steps first. The full mapping between `init` settings and the commands that consume them is in [Initialization § Common init to Execution Mappings](/guide/latest/cli/commandreference/init.md#overview). *** ## 3. Stage 1 — Initial Setup ### Step 1: Activate License AIDC-CLI requires an active license before any commands (except `license`) can be used. ```bash aidc-cli license active -k "YOUR-LICENSE-KEY" ``` ✅ **Expected Result:** ``` License activated successfully! ==================================================== ASUS Infrastructure Deployment Center ==================================================== Server GUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Customer Name: Example Corp License Type: Enterprise Active Date: 2026-02-12T00:00:00Z Expiry Date: 2027-02-12T00:00:00Z Period: 365 days Device Limit: 100 ==================================================== ``` Verify at any time with: ```bash aidc-cli license show ``` {% hint style="warning" %} If the license is expired or invalid, you will see `License is not active. Please activate the application using aidc-cli license`. All commands except `license` will be unavailable — including shell completion. See [Troubleshooting § License Issues](/guide/latest/cli/troubleshooting.md). {% endhint %} ### Step 2: Configure AIDC Common Settings ```bash # View current settings aidc-cli init common-get # Set report path (example) aidc-cli init common-set -r /opt/aidc/reports ``` ### Step 3: Configure BMC Settings Save the BMC credentials once — every BMC-based command (`bmc`, `bios`, `fwupdate`, `hwsensor`, `hwinv`, `chkfw`, …) uses them from here on. ```bash # View current BMC configuration aidc-cli init bmc-get # Set BMC password and network aidc-cli init bmc-set -p "YourBMCPassword" -m 255.255.255.0 -g 192.168.2.1 ``` {% hint style="info" %} When rotating an existing BMC password later, pass the previous password too: `aidc-cli init bmc-set -p "NewPassword" -v "PreviousPassword"`, then apply it on the nodes with [`aidc-cli bmc change-pwd`](/guide/latest/cli/commandreference/bmc.md). {% endhint %} ### Step 4: Prepare Node Inventory Edit your node database CSV file with node information, then render the inventory: ```bash aidc-cli init inventory ``` The command will: 1. Check for duplicate IPs in the CSV 2. Validate the device count against the license limit 3. Render the CSV data into the node inventory 4. Show DHCP validation warnings if applicable {% hint style="warning" %} Re-run `aidc-cli init inventory` **every time the CSV changes** — commands target the rendered inventory, not the CSV itself. {% endhint %} {% hint style="info" %} Fill in the `password` column (node OS password) in the CSV for nodes that **already have an OS** — SSH-based commands use it until key access is in place. Nodes deployed by `aidc-cli deploy install` get SSH key access automatically during installation. {% endhint %} To organize nodes into roles (compute, login, storage, …), fill in the `node_group` column in the CSV and manage the group list: ```bash # View defined groups aidc-cli init group-get # Add groups aidc-cli init group-set -a "computing_node,login_node,management_node" ``` ### Step 5: Configure DHCP (For PXE Deployment) ```bash # Set DHCP parameters aidc-cli init dhcp-set \ -s 192.168.1.0 \ -m 255.255.255.0 \ -r 192.168.1.1 \ -n 192.168.1.10 \ -g 192.168.1.100,192.168.1.200 # Validate CSV IPs fall within the DHCP subnet aidc-cli init dhcp-validate ``` *** ## 4. Stage 2 — OS Deployment See [OS Deployment](/guide/latest/cli/commandreference/deploy.md) for full details. ### Step 6: Select and Download the OS Image ```bash # Discover images already present on the server aidc-cli init image-discovery # List discovered deploy images (note the index numbers) aidc-cli init image-list # Set the active image by index (required flag) aidc-cli init image-active -x 1 ``` If the image is not on the server yet, download it first: ```bash # List images available for download (note the index numbers) aidc-cli init image-downloadable # Mark the image to download by index (required flag) aidc-cli init image-download -x 1 # Download the ISO for the selected image aidc-cli deploy image-download ``` ### Step 7: Deploy the OS ```bash # Pilot first: deploy the OS to a single node aidc-cli deploy install -l node01 # Then deploy to the remaining nodes aidc-cli deploy install ``` {% hint style="info" %} `deploy install` injects the SSH access key during OS installation — no separate key setup is needed for nodes deployed this way. When **adding nodes that already have an OS** (not deployed by AIDC), set up key access with `aidc-cli deploy access-key` (make sure their `password` column in `aidc.csv` is filled first). {% endhint %} {% hint style="warning" %} `deploy install` re-images the target nodes — always pilot on one node with `-l` before a cluster-wide run. The command validates CSV IPs against the DHCP subnet before proceeding; if mismatches are found, you'll be prompted to continue or abort. {% endhint %} *** ## 5. Stage 3 — System Configuration After the OS is installed on the nodes, apply base system settings. See [System Configuration](/guide/latest/cli/commandreference/sysconfig.md). ```bash # Configure all basic system settings at once (SSH, repo, limits, sysctl, hosts, etc.) aidc-cli syscfg basic-all # Set timezone across all nodes aidc-cli syscfg timezone-set -t Asia/Taipei # Configure NTP clients on the nodes aidc-cli syscfg ntp -n "time.google.com,time.cloudflare.com" ``` Individual settings can also be applied one at a time (`syscfg sshd`, `syscfg limits`, `syscfg sysctl`, `syscfg hosts`, …) — see the [SysConfig subcommand list](/guide/latest/cli/commandreference/sysconfig.md). *** ## 6. Stage 4 — Network and Drivers ### Step 8: Configure Node Networking Network configuration is a two-step process: save the profile with `init`, then apply it with `network`. See [Network Configuration](/guide/latest/cli/commandreference/network.md). ```bash # 1) Save the profiles aidc-cli init eth-set # Ethernet aidc-cli init bond-set # Bonding aidc-cli init ib-set # InfiniBand # 2) Apply them on the nodes aidc-cli network eth-cfg aidc-cli network eth-bond aidc-cli network ib-cfg ``` Verify connectivity as soon as the network is up: ```bash aidc-cli chknet pxe # PXE network aidc-cli chknet bmc # BMC network aidc-cli chknet ib # InfiniBand / Ethernet link ``` ### Step 9: Install Drivers See [Driver Installation](/guide/latest/cli/commandreference/driver.md). ```bash # See what is already installed aidc-cli driver discover # Install Mellanox OFED aidc-cli driver mlnx-ofed -f MLNX_OFED_LINUX-24.04-0.6.6.0 # Install NVIDIA GPU driver (caution: forces reboot) aidc-cli driver nv-gpu -f NVIDIA-Linux-x86_64-550.54.15.run ``` *** ## 7. Stage 5 — Firmware Baseline (Optional) Check the firmware landscape before production, and update where needed. See [Firmware Validation](/guide/latest/cli/commandreference/firmwarevalidation.md) and [Firmware Update](/guide/latest/cli/commandreference/firmwareupdate.md). ```bash # Survey current firmware versions across the cluster aidc-cli chkfw summary # Update on a single node first, then roll out aidc-cli fwupdate bios --backend tool -l node01 aidc-cli fwupdate bmc --backend tool -l node01 ``` {% hint style="warning" %} Firmware updates are not reversible and may require reboots. Always pilot with `-l `, verify with `chkfw`, and only then widen the scope. {% endhint %} *** ## 8. Stage 6 — Services and Storage Each service follows the same pattern: **configure with `init`, then deploy**. Pick the ones your cluster needs. | Service | 1) Configure | 2) Deploy | Details | | --------------- | ----------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------- | | Slurm | `aidc-cli init slurm-set` | `aidc-cli slurm setup-cluster` | [Slurm](/guide/latest/cli/commandreference/slurm.md) | | Kubernetes | `aidc-cli init k8s-set` | `aidc-cli kubernetes k8s-native` | [Kubernetes](/guide/latest/cli/commandreference/kubernetes.md) | | Docker / Podman | `aidc-cli init container-set` | `aidc-cli container docker` | [Container](/guide/latest/cli/commandreference/container.md) | | Harbor registry | `aidc-cli init harbor-set` | `aidc-cli container harbor` | [Container](/guide/latest/cli/commandreference/container.md) | | MariaDB Galera | `aidc-cli init mariadb-set` | `aidc-cli database maria-galera` | [Database](/guide/latest/cli/commandreference/database.md) | | UFM | `aidc-cli init ufm-set` | `aidc-cli ufm deploy` | [UFM](/guide/latest/cli/commandreference/ufm.md) | | NMX-M VMs | `aidc-cli init nmx-set` | `aidc-cli nmx deploy -W ... -E ... -V ...` | [NMX](/guide/latest/cli/commandreference/nmx.md) | | WEKA storage | — | `aidc-cli weka server deploy -I ` | [WEKA](/guide/latest/cli/commandreference/weka.md) | | Ceph storage | — | `aidc-cli ceph server deploy -r -m -p ` | [Ceph](/guide/latest/cli/commandreference/ceph.md) | Example — Slurm cluster: ```bash # Configure the node groups and accounting credentials aidc-cli init slurm-set -t headnode -c computing_node -d db_node # Deploy controller + compute + database aidc-cli slurm setup-cluster # Later: add more compute nodes aidc-cli slurm slurmd -c node11,node12 ``` *** ## 9. Stage 7 — Validate and Create a Golden Baseline Once the cluster is up, capture its healthy state so future drift is detectable. See [SAT Baselines and Validation](/guide/latest/cli/commandreference/sat.md). ```bash # Validate network connectivity aidc-cli chknet pxe aidc-cli chknet bmc # Run hardware health checks aidc-cli chkhw summary # Survey firmware versions aidc-cli chkfw summary # Collect hardware and OS configuration summaries aidc-cli hwspec summary aidc-cli osinfo summary # Snapshot everything as a golden baseline aidc-cli sat baseline create --name golden-v1 ``` Whenever something changes later (firmware update, driver reinstall, node replacement), validate against the baseline: ```bash aidc-cli sat validate --baseline golden-v1 ``` *** ## 10. Day-2 Operations ### Reports Long-running commands write report files under the report path (set in Step 2). See [Report Files](/guide/latest/cli/commandreference/report.md). ```bash # List the newest reports aidc-cli report list # Show one report aidc-cli report show ``` ### Sensor Monitoring ```bash # Monitor temperatures every 5 seconds, in the background aidc-cli hwsensor temperature --interval 5 -b # One-shot view of all BMC sensors aidc-cli hwsensor all --times 1 ``` ### Server Information ```bash # Collect an AIDC Server system information report aidc-cli sysinfo ``` ### AI Assistant (Optional) AIDC-CLI includes a natural-language assistant that can run CLI operations for you. Configure a provider once, then chat: ```bash # One-time setup: pick a provider (enter its API key when prompted) and a model aidc-cli ai model # Ask in natural language aidc-cli ai chat -q "check the firmware versions on node01" ``` See [AI Assistant](/guide/latest/cli/commandreference/ai.md) for providers, skills, and safety confirmation behavior. *** ## 11. Common Patterns ### Targeting Specific Nodes ```bash # Run only on node01 and node02 aidc-cli bmc power-on -l node01,node02 # Run on all nodes except node03 aidc-cli deploy install -e node03 ``` {% hint style="info" %} **Pilot-first habit:** for anything that changes node state (`deploy`, `fwupdate`, `network`, `syscfg`, `driver`), run with `-l ` first, verify, then widen the scope. Running without `-l` targets the whole inventory and asks for confirmation. {% endhint %} ### Tracking Operations with Task IDs Attach a task ID to correlate an operation with its report and audit logs: ```bash aidc-cli fwupdate bmc --backend tool -l node01 -i TASK-FW-0042 aidc-cli report list --match TASK-FW-0042 ``` ### Background Execution Some long-running tasks support background mode: ```bash # Run hardware sensor monitoring in the background aidc-cli hwsensor temperature --interval 5 -b ``` ### JSON / stdout Output Some commands support machine-readable output for automation: ```bash # License info in JSON aidc-cli license show -j # Network validation with stdout JSON aidc-cli chknet pxe -o # Hardware inventory to stdout aidc-cli hwinv all --stdout ``` See [Common Flags and Options](/guide/latest/cli/commonflags.md) for the full flag reference. *** ## 12. Next Steps * [Command Reference](/guide/latest/cli/commandreference.md) — Full list of all commands and subcommands * [Initialization](/guide/latest/cli/commandreference/init.md) — Every `init` setting in detail, with the init-to-execution mapping * [Common Flags and Options](/guide/latest/cli/commonflags.md) — Detailed flag documentation * [Troubleshooting](/guide/latest/cli/troubleshooting.md) — Common issues and solutions