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.
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
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
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
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.