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

# CLI Usage

> Install the Gravix Layer CLI, authenticate, and manage sandboxes from your terminal

Create and manage runtimes (sandboxes) with the `gravixlayer` CLI (`grx` symlink included).

## Install

### macOS / Linux

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl -fsSL https://cli.gravixlayer.ai/install | sh
```

Installs to `~/.local/bin` by default and adds it to your PATH when needed.

Pin a version:

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
GRAVIXLAYER_VERSION=v0.1.0 curl -fsSL https://cli.gravixlayer.ai/install | sh
```

### Windows (PowerShell)

```powershell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
irm 'https://cli.gravixlayer.ai/install.ps1' | iex
```

### Verify

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
gravixlayer --version
# or
grx --version

gravixlayer doctor
```

## Authenticate

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
gravixlayer auth login
```

Paste your API key from the [console](https://app.gravixlayer.ai). The CLI verifies it, then stores it in your OS keychain for the active **profile**.

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Check that a key is stored and valid
gravixlayer auth status

# Or set the key for this shell only (overrides the keyring)
export GRAVIXLAYER_API_KEY="your-api-key"
```

## Profiles

Config lives at `~/.gravixlayer/config.toml`. Each **profile** has its own defaults and keyring entry (so you can keep staging and production separate).

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# List profiles (* marks the active one)
gravixlayer config profiles

# Switch the default profile
gravixlayer config use-profile default

# Override for a single command
gravixlayer --profile staging runtime list

# Or via env
export GRAVIXLAYER_PROFILE=staging
```

Set per-profile defaults:

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
gravixlayer config set base_url https://api.gravixlayer.ai
gravixlayer config set default_template base-small
gravixlayer config set default_cloud azure
gravixlayer config set default_region eastus2

# Target another profile without switching
gravixlayer config set default_region westus2 --profile staging
```

Show config (API keys are redacted):

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
gravixlayer config show
```

`gravixlayer doctor` prints the active profile, config path, base URL, and whether a key is in the keyring.

## Create and use a sandbox

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Create a runtime (prints the runtime id)
gravixlayer runtime create --template base-small --wait

# List sandboxes
gravixlayer runtime list

# Machine-readable output (global flag)
gravixlayer --output json runtime list

# Run a one-liner inside the sandbox
gravixlayer runtime exec <runtime-id> python -c 'print(2 + 2)'

# Or upload and run a local script file
gravixlayer runtime run <runtime-id> ./hello.py

# Interactive shell
gravixlayer runtime shell <runtime-id>

# Terminate when finished
gravixlayer runtime kill <runtime-id>
```

Output formats: `--output table` (default), `--output json`, or `--output quiet`.\
You can also set `GRAVIXLAYER_OUTPUT=json`.

## Files

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Write a file (path then content)
gravixlayer runtime files write <runtime-id> /workspace/hello.txt 'Hello'

# Read it back
gravixlayer runtime files cat <runtime-id> /workspace/hello.txt

# List the workspace
gravixlayer runtime files ls <runtime-id> /workspace
```

## Update

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Check for a newer release
gravixlayer update --check

# Install the latest stable release
gravixlayer update

# Install a specific version
gravixlayer update --version 0.1.1
```

Or re-run the install script:

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl -fsSL https://cli.gravixlayer.ai/install | sh
```

## Uninstall

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Default install location
rm -f ~/.local/bin/gravixlayer ~/.local/bin/grx

# Optional: remove local config and cached auth
rm -rf ~/.gravixlayer

# If you previously installed under /usr/local/bin
# sudo rm -f /usr/local/bin/gravixlayer /usr/local/bin/grx
```

Windows (PowerShell):

```powershell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Remove-Item "$env:LOCALAPPDATA\gravixlayer" -Recurse -Force
```

## What’s next

<CardGroup cols={2}>
  <Card title="SDK Usage" icon="code" href="/documentation/agentruntime/sdk-usage">
    Same sandbox workflows in Python
  </Card>

  <Card title="API Keys" icon="key" href="/documentation/agentruntime/getting-started/api-keys">
    Create and manage API keys
  </Card>

  <Card title="Create Runtime" icon="server" href="/documentation/agentruntime/sandbox-management/create-sandbox">
    Templates, cloud, region, and attach options
  </Card>

  <Card title="Quickstart" icon="rocket" href="/documentation/agentruntime/getting-started/quickstart">
    End-to-end SDK walkthrough
  </Card>
</CardGroup>