> ## Documentation Index
> Fetch the complete documentation index at: https://docs.godrift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands Reference

> Complete reference for Drift CLI commands and slash commands

Drift CLI accepts two kinds of input: **natural language prompts** and **slash commands**. Natural language prompts are interpreted by the AI agent. Slash commands execute immediately, without the agent.

## Slash Commands

| Command                 | Description                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| `/help`                 | Show comprehensive help with all commands and usage examples                                              |
| `/init`                 | Scan the current workspace and write a starter `DRIFT.md` so Drift remembers your project on every prompt |
| `/skill add <path>`     | Add a custom skill from a `.md` file. Drift will use it from the next prompt onward                       |
| `/skill list`           | Show every skill currently active for this workspace                                                      |
| `/skill remove <name>`  | Drop a custom skill                                                                                       |
| `/ps` (or `/processes`) | Show all running background processes (ROS2 nodes, Gazebo, MuJoCo viewer, etc.)                           |
| `/version`              | Display the current Drift CLI version                                                                     |
| `/update`               | Update Drift CLI to the latest available version                                                          |
| `/login`                | Sign in to your Drift account                                                                             |
| `/logout`               | Sign out of your Drift account                                                                            |
| `/profile`              | Show the signed-in account and usage info                                                                 |
| `/clear`                | Clear the terminal screen                                                                                 |
| `/exit` (or `/quit`)    | Exit Drift CLI                                                                                            |

## CLI Flags

These flags are used when launching Drift from your shell (not from the `drift>` prompt):

| Flag                  | Description                                                |
| --------------------- | ---------------------------------------------------------- |
| `drift --help`        | Show help information                                      |
| `drift --version`     | Print version and exit                                     |
| `drift init`          | Initialize a new Drift project in the current directory    |
| `drift simulate`      | Start a simulation directly (skips the interactive prompt) |
| `drift -c "<prompt>"` | Run a single prompt non-interactively and exit             |

### `drift init`

Run in an empty directory to scaffold a new project — workspace structure plus an initial `DRIFT.md` so the agent has context from prompt #1.

```bash theme={null}
mkdir my-robot && cd my-robot
drift init
drift  # open the interactive shell in the initialized project
```

### `drift simulate`

Launch a simulation from the command line without entering the interactive `drift>` shell. Useful for scripting or CI scenarios where you want to start a pre-built simulation non-interactively.

```bash theme={null}
drift simulate
```

If no project is found in the current directory, Drift will prompt you to run `drift init` first.

### `drift -c "<prompt>"`

Run a single prompt non-interactively — Drift executes the task, auto-approves all steps, and exits cleanly when done. Useful for CI pipelines, batch testing, or quick one-offs from a script.

```bash theme={null}
drift -c "create a ROS2 package called sensor_fusion with ament_python build type"
drift -c "add a lidar to my robot's URDF at position 0 0 0.3"
drift -c "build the workspace and run the tests"
```

## Natural Language Commands

At the `drift>` prompt, you can type any request in plain English. Common categories:

### Create

| Example                                                               | What it does                                                                    |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `create a differential drive robot with a lidar and camera`           | Generates URDF with wheel geometry, sensor mounts, Gazebo plugins, launch files |
| `create a six-axis manipulator with a gripper`                        | Scaffolds full robot description with controller configs and launch files       |
| `create a warehouse environment`                                      | Generates a Gazebo world with warehouse objects                                 |
| `build a 4-wheel mobile robot in MuJoCo with an IMU and force sensor` | Authors MJCF with bodies, joints, actuators, sensors                            |
| `set up a pick-and-place simulation`                                  | Creates a complete simulation: robot, world, launch files                       |

### Modify

| Example                                                                | What it does                                                         |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `add a lidar sensor to my robot at position 0 0 0.3 and rebuild`       | Updates URDF / MJCF, configures the sensor, rebuilds the workspace   |
| `add an IMU sensor and update the launch file to bridge the IMU topic` | Edits URDF, bridge config, and launch file in one coordinated change |
| `change the gripper to a suction cup`                                  | Updates the robot's end effector configuration                       |
| `add three obstacle boxes to my MuJoCo scene at random positions`      | Modifies the MJCF scene with new bodies                              |
| `add obstacles to my Gazebo world`                                     | Modifies the SDF world file                                          |

### Launch & Inspect

| Example                                                            | What it does                                                                  |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `launch my robot in Gazebo with the warehouse world and open RViz` | Starts Gazebo, spawns robot, opens RViz with the right config, bridges topics |
| `open the scene in the MuJoCo viewer`                              | Opens the MuJoCo passive viewer for the current MJCF                          |
| `run the headless MuJoCo sim for 10 seconds and log IMU to CSV`    | Runs a non-interactive sim with sensor logging                                |
| `what topics is my robot publishing?`                              | Lists active ROS2 topics                                                      |
| `echo the lidar scan data`                                         | Streams live output from the topic                                            |
| `set the max_velocity parameter on the navigation node to 1.5`     | Sets a ROS2 node parameter directly                                           |
| `run ros2 doctor`                                                  | Checks your ROS2 environment for common issues                                |

### Build

| Example                                 | What it does                                                                       |
| --------------------------------------- | ---------------------------------------------------------------------------------- |
| `build my workspace and fix any errors` | Runs colcon, reads errors, edits CMakeLists.txt / package.xml / setup.py as needed |
| `what went wrong with the last build?`  | Analyzes build output and explains the root cause                                  |
| `find all launch files in my workspace` | Searches across packages and lists matching files                                  |

### Debug

| Example                                                 | What it does                                                              |
| ------------------------------------------------------- | ------------------------------------------------------------------------- |
| `why is my robot not moving when I publish to cmd_vel?` | Checks topic connections, QoS compatibility, controller chain             |
| `why isn't my camera publishing images?`                | Inspects topic list, sensor config, plugin setup                          |
| `my robot spawns but falls through the ground — fix it` | Validates URDF inertia tensors, collision geometry, chassis-z spawn rules |
| `qacc has NaN in my MuJoCo sim — what's causing it?`    | Walks through inertia, timestep, contact tuning, joint damping checks     |
| `the wheels spin but the robot doesn't move`            | Diagnoses cylinder axis vs hinge axis, friction, contact configuration    |

## Quick Reference

| What you need             | What to say                                                               |
| ------------------------- | ------------------------------------------------------------------------- |
| New robot project         | `create a mobile robot with differential drive and a depth camera`        |
| MuJoCo scene              | `build a 4-wheel robot in MuJoCo and drive it forward for 5 seconds`      |
| Fix a broken build        | `build my workspace and fix the errors`                                   |
| Debug simulation          | `my robot spawns but doesn't move — figure out why`                       |
| Sensor setup              | `add a 2D lidar to my robot and bridge it to ROS2`                        |
| Launch configuration      | `generate a launch file for my robot in Gazebo with RViz`                 |
| ROS2 inspection           | `list all active topics and show me what /camera/image_raw is publishing` |
| Parameter tuning          | `set the PID gains on the left wheel controller to P=10 I=0.1 D=0.5`      |
| File operations           | `find all launch files in my workspace and show me which ones use Gazebo` |
| Quick automation          | `drift -c "create a test world with 10 random obstacles"`                 |
| Hand off team knowledge   | `/skill add ./team-docs/ekf-tuning.md`                                    |
| Bootstrap project context | `/init`                                                                   |

## Execution Control

### Pausing mid-execution

Press **`ESC`** at any point during a multi-step execution to pause. Drift remembers exactly what's been completed and what's still pending — nothing is lost.

When paused, you'll be prompted to choose how to proceed:

| Option                       | What it does                                               |
| ---------------------------- | ---------------------------------------------------------- |
| **Yes — apply and continue** | Run the next pending command and pause again               |
| **Yes to all (session)**     | Auto-approve every command for the rest of this session    |
| **Yes to all (this run)**    | Auto-approve for the current task only, then resume asking |
| **No — skip and stop**       | Cancel execution and return to the `drift>` prompt         |

This gives you full control — step through carefully when trying something new, or let Drift run freely once you're confident.

## Auto-Update

When a new version is available, Drift shows a notification on startup:

```
ℹ️ A new version (x.x.x) is available. Type /update to install.
```

Run `/update` to install the latest version. If you see **"Mandatory update required"**, your version is too old to work with current services — `/update` (or re-install) is required before continuing.