(cli_overview)=

# XCOMPUTE CLI

Welcome to the command reference for the XCOMPUTE platform. The CLI provides a hierarchical, context-aware interface for configuring, querying, and executing workflows. All commands follow a strict `<verb> <noun> [arguments...]` structure.

## 🧭 Navigation by Verb Category

The command dispatcher routes all requests through three canonical verbs:

| Verb | Purpose | Command Reference |
|:---|:---|:---|
| `get` | Query system state, metadata, and physical properties (read-only) | [📄 getter commands](getters.md) |
| `set` | Configure parameters, boundary conditions, and spatial transforms (state mutation) | [📄 setter commands](setters.md) |
| `do` | Execute workflows, I/O operations, simulation dispatch, and administrative actions | [📄 doer commands](doers.md) |

## 📘 Quick Reference & Usage Patterns

### 🔠 Basic Syntax
```text
<verb> <noun> [arg1 arg2 ...]
# Examples:
get files
set units mm
do solve
```

### ℹ️ Built-in Help System
The CLI includes a recursive help interface accessible from any context:
- `help` or `get help` → Overview of verbs and structure
- `help get` / `help set` / `help do` → Category-specific command lists
- `help <noun>` → Detailed syntax, arguments, and physical context for a specific command

### 📐 Platform Conventions
1. **Hierarchy**: All commands follow `<verb> <noun> [args...]`. Legacy verbs (`enable`, `new`, `check`, etc.) are normalized at parse time.
2. **Dimensional Consistency**: Geometric units `[L]` are local to the system. Global physical quantities (mass, energy, flux, solver tolerances) are strictly maintained in SI (`kg`, `m`, `s`, `A`, `K`).
3. **Conserved Quantities**: Commands touching contacts, couplings, or solvers are annotated with flux/continuity constraints to guide physics-first implementation.
4. **Permissions**: Admin-gated commands require `usr ∈ {admin[0], admin[1]}`. All others pass `checkPermissions(sys, usr)`.

## 🔗 Next Steps

- **New to XCOMPUTE?** Start with `get info` and `help` to explore system capabilities.
- **Building a simulation?** Use `set units`, `set model`, and `do solve` to configure and dispatch jobs.
- **Managing data pipelines?** Refer to `do import`, `do export`, and `do attach` for I/O and provenance tracking.
- **Developing integrations?** Leverage the normalized verb structure to build terminal wrappers, GUI clients, or edge-device bridges.