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

# GRID CLI

> Command reference for the GRID Enterprise interactive shell

The GRID CLI is an interactive shell that orchestrates GRID containers and sessions. Launch it by typing `grid` inside your Python environment.

```bash theme={null}
grid
```

<Accordion title="Show Expected Output">
  ```text theme={null}
   .d8888b.  8888888b.  8888888 8888888b.
  d88P  Y88b 888   Y88b   888   888  "Y88b
  888    888 888    888   888   888    888
  888        888   d88P   888   888    888
  888  88888 8888888P"    888   888    888
  888    888 888 T88b     888   888    888
  Y88b  d88P 888  T88b    888   888  .d88P
   "Y8888P88 888   T88b 8888888 8888888P"

  General Robot Intelligence Development Platform - Enterprise version
  General Robotics Technology, Inc.

  Type help for list of commands.

  GRID #
  ```
</Accordion>

<Note>
  Commands target the default node unless you specify one with `@nodename` (e.g., `init airgen @lab-gpu-0`). Use `node list` and `node select` to manage nodes.
</Note>

***

## Quick Reference

| Command                       | Description                               |
| ----------------------------- | ----------------------------------------- |
| `login`                       | Authenticate with the container registry  |
| `init [sim]`                  | Start GRID containers                     |
| `terminate`                   | Stop GRID containers                      |
| `update [sim]`                | Pull latest containers and refresh assets |
| `update assets`               | Force redownload simulator assets         |
| `update samples`              | Update sample notebooks                   |
| `session start <id> [config]` | Start a simulation session                |
| `session stop [id]`           | Stop a session                            |
| `session list`                | List active sessions                      |
| `open nb\|sim\|viz\|code\|ui` | Open interfaces in browser/IDE            |
| `logs <source> [N]`           | View logs                                 |
| `node list\|select`           | Manage target nodes                       |
| `help [cmd] [subcmd]`         | Show help                                 |

***

## Node Management

<CardGroup cols={2}>
  <Card title="node list" icon="list">
    Display all configured nodes and their IP addresses.
  </Card>

  <Card title="node select" icon="circle-check">
    Set the default target node for subsequent commands.
  </Card>
</CardGroup>

```bash theme={null}
node list
node select lab-gpu-0
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  +----------+-------------+
  | Node Name| IP Address  |
  +==========+=============+
  | local    | 127.0.0.1   |
  | lab-gpu-0| 10.40.0.10  |
  +----------+-------------+
  Default node set to lab-gpu-0
  ```
</Accordion>

<Note>Need to add or edit nodes? See [Remote Nodes & Client Mode](./remote-nodes).</Note>

***

## Authentication

### login

Authenticates with the GRID container registry using credentials from your `license.json`. Required before pulling container images.

```bash theme={null}
login @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Logging in to General Robotics – GRID registry...
  Login successful!
  ```
</Accordion>

***

## Container Lifecycle

### init

Spins up GRID containers on the target node. Supported simulators: `airgen`, `isaac`, `isaac5`.

```bash theme={null}
init airgen @local
init isaac --verbose @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Initializing assets …
  Assets initialized.
  Starting airgen on local …
  Checking container statuses...
  grid_core: ✓
  grid_server: ✓
  grid_sim_airgen: ✓
  Containers are active.
  ```
</Accordion>

### terminate

Stops all GRID containers on the target node.

```bash theme={null}
terminate @local
terminate --verbose @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Checking container statuses...
  grid_core: ✗
  grid_server: ✗
  grid_sim_airgen: ✗
  Containers stopped successfully.
  ```
</Accordion>

***

## Updates

<CardGroup cols={3}>
  <Card title="update" icon="arrows-rotate">
    Pull latest container images and refresh assets.
  </Card>

  <Card title="update assets" icon="download">
    Force redownload simulator environment assets.
  </Card>

  <Card title="update samples" icon="book">
    Update sample notebooks from the repository.
  </Card>
</CardGroup>

### update

Pulls the latest container images and refreshes shared assets.

```bash theme={null}
update airgen @local
update isaac --verbose @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Checking for updates …
  ✔ sim-airgen Pulled
  ✔ core Pulled
  ✔ server Pulled
  Updating assets …
  Assets initialized.
  ```
</Accordion>

### update assets

Force redownloads simulator assets for the active sim. Useful when assets are corrupted or you need the latest environment files.

```bash theme={null}
update assets @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Updating assets for airgen (force redownload) …
  Sim assets updated.
  ```
</Accordion>

### update samples

Updates the sample notebooks repository while preserving local changes like Jupyter checkpoints.

```bash theme={null}
update samples @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Updating sample notebooks …
  Sample notebooks updated.
  ```
</Accordion>

***

## Session Management

### session start

Starts a session with the specified ID. If no config is provided, a sample configuration is generated automatically.

```bash theme={null}
session start demo
session start demo ~/my_config.json @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Using sample config at /home/grid/.grid/sample_session_airgen.json
  Starting session demo on node local …
  Status: Initializing session...
  Status: Session has been started successfully
  Session started successfully.
  ```
</Accordion>

### session stop

Stops a running session.

```bash theme={null}
session stop demo
session stop @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  Stopping session demo on node local …
  Session stopped.
  ```
</Accordion>

### session list

Lists all active sessions across nodes.

```bash theme={null}
session list
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  +----------+--------+-------------------------------+
  | Session  | Node   | Last active                   |
  +==========+========+===============================+
  | demo     | local  | 2025-02-11T23:24:32.991267+00 |
  +----------+--------+-------------------------------+
  ```
</Accordion>

***

## Interfaces

### open

Opens the corresponding interface for your active session.

| Interface | Description                              |
| --------- | ---------------------------------------- |
| `nb`      | Jupyter notebook                         |
| `sim`     | Simulation stream                        |
| `viz`     | Rerun visualization                      |
| `ui`      | Web UI                                   |
| `code`    | VS Code attached to grid\_core container |

```bash theme={null}
open nb @local
open sim @local
open viz @local
open code @local
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  If you are running the setup in your machine - http://127.0.0.1:8890
  If you are running this setup from a VM - http://<vm_ip>:8890
  ```
</Accordion>

<Note>
  The `open code` command attaches VS Code directly to the `grid_core` container. Requires VS Code with the Dev Containers extension. See [VS Code with GRID Containers](./vscode-containers) for details.
</Note>

***

## Logs & Diagnostics

### logs

Shows the last N lines (default: 100) from the specified log source.

| Source      | Description                 |
| ----------- | --------------------------- |
| `commander` | Commander server logs       |
| `session`   | Session manager logs        |
| `repl`      | CLI/REPL logs               |
| `core`      | grid\_core container logs   |
| `server`    | grid\_server container logs |
| `sim`       | Simulator container logs    |

```bash theme={null}
logs commander 50
logs core 100
logs sim
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  --- Last 50 lines from commander log (/home/grid/.grid/grid_commander.log) ---
  2025-02-11 20:40:13 | INFO | grid.commander | Simulation profile set to airgen
  2025-02-11 20:40:14 | INFO | grid.commander | Attempting ACR login...
  ```
</Accordion>

***

## Getting Help

The `help` command supports both commands and subcommands:

```bash theme={null}
help                    # List all commands
help update             # Help for update command
help session start      # Help for session start subcommand
help open nb            # Help for specific interface
```

<Accordion title="Show Expected Output">
  ```text theme={null}
  GRID # help session start
  Start a new simulation session.

     Usage: session start <id> [config] [@nodename]

     Arguments:
       <id>       — Unique session identifier
       [config]   — Path to session config file (optional)
       [@node]    — Target node (default: local)
  ```
</Accordion>