Introduction

oxide is a command-line interface to the Oxide API for use in scripts or the terminal.

Installation

You can find builds of the oxide CLI here.

On macOS, you can install it via Homebrew with:

brew install oxidecomputer/tap/oxide-cli

Authentication

To create an API token that can be used for all client tools, please refer to the CLI Quick Start. There are two ways to specify authentication information when using the CLI:

Environment variables

You can set the OXIDE_HOST and OXIDE_TOKEN environment variables. This method is useful for service accounts.

Configuration file

oxide auth login generates a file at $HOME/.config/oxide/credentials.toml. This file contains sensitive information such as your token and user ID.

If you have multiple credentials set up (e.g., for different hosts or different silos on the same host), choose one by setting default-profile in $HOME/.config/oxide/config.toml or passing --profile to any CLI command.

Response codes

Failed requests return both the API error messages and standard HTTP response codes. Read the API Responses guide for more information.

Examples

The CLI Quick Start guide covers an end-to-end example on how to create a SSH key for your account, import a guest image to create an Oxide disk image, and create an instance from the image.

Certain CLI requests take nested json input in a json-body argument, including the disk and instance provisioning requests. Here are some examples:

Create instance from image

Use oxide instance from-image.

oxide instance from-image \
   --image bookworm \
   --name pegasus \
   --project prototypes \
   --description "Phasing cloaking device" \
   --hostname pegasus \
   --memory 16g \
   --ncpus 8 \
   --size 200g \
   --start

Create disk from image

Use oxide disk create.

oxide disk create --project myproj --json-body request.json

// request.json
{
  "name": "boot-disk",
  "description": "from an existing image",
  "size": 4294967296,
  "disk_source": {
    "type": "image",
    "image_id": "afe0344d-124a-412c-8939-8f086f187d22"
  }
}

Create blank disk

Use oxide disk create.

oxide disk create --project myproj --json-body request.json

// request.json
{
  "name": "data-disk",
  "description": "blank disk for data storage",
  "size": 21474836480,
  "disk_source": {
    "type": "blank",
    "block_size": 4096
  }
}

Create instance with existing disks

Use oxide instance create.

oxide instance create --project myproj --json-body request.json

// request.json
{
  "name": "myinstance",
  "description": "my first Oxide instance",
  "hostname": "myinst",
  "memory": 4294967296,
  "ncpus": 2,
  "disks": [
    {
      "type": "attach",
      "name": "boot-disk"
    },
    {
      "type": "attach",
      "name": "data-disk"
    }
  ],
  "network_interfaces": {
    "type": "default"
  },
  "external_ips": [
    {
      "type": "ephemeral",
      "pool_name": "default"
    }
  ],
  "start": true
}

Create instance with new disks

Use oxide instance create.

oxide instance create --project myproj --json-body request.json

// request.json
{
  "name": "myinstance2",
  "description": "my second Oxide instance",
  "hostname": "myinst2",
  "memory": 4294967296,
  "ncpus": 2,
  "disks": [
    {
      "type": "create",
      "name": "ubuntu-disk",
      "description": "from a project image",
      "size": 4294967296,
      "disk_source": {
        "type": "image",
        "image_id": "afe0344d-124a-412c-8939-8f086f187d22"
      }
    },
    {
      "type": "create",
      "name": "additional-disk",
      "description": "blank disk for data storage",
      "size": 21474836480,
      "disk_source": {
        "type": "blank",
        "block_size": 4096
      }
    }
  ],
  "network_interfaces": {
    "type": "default"
  },
  "external_ips": [
    {
      "type": "ephemeral",
      "pool_name": "default"
    }
  ],
  "user_data": "$(cat mycloudinit.yaml | base64)",
  "start": true
}

Support

Report bugs or search for existing feature requests in our issue tracker.

Introduction

Table of Contents