raff-cli

raff

Raff CLI — manage cloud resources from the terminal

Usage:
  raff [command]

Available Commands:
  api-key        Manage API keys
  backup         Manage VM backups (incl. `raff backup schedule`)
  completion     Generate the autocompletion script for the specified shell
  configure      Configure API credentials and defaults
  help           Help about any command
  invitation     Send and cancel email invitations
  ip             Manage floating IPs
  member         Manage account-level members
  permission     List the permission catalog
  pricing        Browse the public pricing catalog
  project        Manage projects (incl. `raff project member`)
  region         List datacenter regions
  role           Manage IAM roles
  security-group Manage security groups
  snapshot       Manage VM and volume snapshots
  ssh-key        Manage SSH keys
  template       List OS templates
  version        Show the current version
  vm             Manage virtual machines
  volume         Manage block storage volumes
  vpc            Manage virtual private clouds

Flags:
      --api-key string      API key (overrides config)
      --api-url string      API base URL (overrides config)
  -h, --help                help for raff
  -o, --output string       Output format: table or json (default "table")
      --project-id string   Default project ID (overrides config)
  -v, --version             version for raff

Use "raff [command] --help" for more information about a command.

See the full reference documentation for information about each available command.

What's new in v0.3.6 — MAC column on raff vm networks, raff vm create --no-vpc, base disk vs attached volumes split on raff vm get, "Attached VMs" relabel on security groups, --type help enumerates nvme, plus the API-side fixes that make raff volume create work without a --pricing-id flag (auto-derived from --type + --region) and --filesystem ext4 actually honored. Full details in the API changelog.

• Installing raff
  • Downloading a Release from GitHub
  • Building the Development Version from Source
• Authenticating with Raff
  • Switching between multiple profiles
• Configuring Default Values
  • Environment Variables
• Enabling Shell Auto-Completion
  • Linux Auto Completion
  • macOS Auto Completion
• Uninstalling raff
• Examples
• Documentation
• Related projects

Installing raff

Downloading a Release from GitHub

Visit the Releases page for archives matching your OS / architecture. Builds are published for linux, macos, windows × amd64, arm64.

Quickest — auto-detect the latest version

# Linux x86_64
curl -sL "https://api.github.com/repos/RaffTechnologies/raff-cli/releases/latest" \
  | grep "browser_download_url.*linux_x86_64.tar.gz" \
  | cut -d'"' -f4 | xargs curl -sL | tar -xzv
sudo mv raff /usr/local/bin/

Replace linux_x86_64 with linux_arm64, macos_x86_64, or macos_arm64 as needed.

Pinning to a specific version

Replace 0.3.6 below with the version you want from the Releases page.

# Linux x86_64
curl -sL https://github.com/RaffTechnologies/raff-cli/releases/download/v0.3.6/raff_0.3.6_linux_x86_64.tar.gz | tar -xzv
sudo mv raff /usr/local/bin/

# macOS arm64 (Apple Silicon)
curl -sL https://github.com/RaffTechnologies/raff-cli/releases/download/v0.3.6/raff_0.3.6_macos_arm64.tar.gz | tar -xzv
sudo mv raff /usr/local/bin/

For Windows, download the matching .zip from the Releases page in your browser, extract raff.exe, then follow How to: Add Tool Locations to the PATH Environment Variable to put it on your PATH.

Verify the install:

raff --version

Building the Development Version from Source

If you have a Go environment configured, you can install the development version of raff from the command line:

go install github.com/rafftechnologies/raff-cli/cmd/raff@latest

While the development version is a good way to take a peek at the latest features before they're released, be aware that it may have bugs. Officially released versions will generally be more stable.

Or build from a clone:

git clone https://github.com/RaffTechnologies/raff-cli.git
cd raff-cli
make build       # produces ./bin/raff
make install     # installs into $GOBIN

Requires Go 1.25+.

Authenticating with Raff

To use raff, you need an API key. Generate one in the dashboard at rafftechnologies.com under Team & Projects → API Keys.

Run the configure command to set up a profile:

raff configure

You'll be prompted for three fields, each with the existing value as the default (just press Enter to keep it):

API URL [https://api.rafftechnologies.com]:
API Key [...]: raff_pub_xxx
Default Project ID (optional) [...]: 11111111-2222-3333-4444-555555555555

When you finish, you'll see:

Profile "default" saved to /home/you/.raff/config.yaml

The active profile becomes the one you just configured. Subsequent raff commands read credentials from this file.

Note: configure does not currently validate the key against the API — it just saves to disk. The first real call (e.g. raff project list) will surface an auth error if the key is wrong.

Switching between multiple profiles

raff supports multiple profiles in the same config file so you can keep separate keys (e.g. staging vs production):

raff configure                    # writes/updates the "default" profile
raff configure --profile staging  # writes/updates the "staging" profile and makes it active
raff configure --profile default  # switch back to "default" (just press Enter through the prompts)

Other commands (vm list, vpc list, …) do not take a --profile flag — they always use whichever profile is set as current-profile in ~/.raff/config.yaml. To use a non-active profile for a single command, override with environment variables:

RAFF_API_KEY=raff_pub_yyy RAFF_PROJECT_ID=<staging-project-uuid> raff vm list

Or with command-line flags:

raff vm list --api-key raff_pub_yyy --project-id <staging-project-uuid>

Configuring Default Values

The raff configuration file stores your API key and default values for command flags. The file is created automatically the first time you run raff configure.

OS	Config path
Linux	~/.raff/config.yaml
macOS	~/.raff/config.yaml
Windows	%USERPROFILE%\.raff\config.yaml

Example file with two profiles:

current-profile: default
profiles:
  default:
    api-url: https://api.rafftechnologies.com
    api-key: raff_pub_xxx
    project-id: 11111111-2222-3333-4444-555555555555
  staging:
    api-url: https://api.rafftechnologies.com
    api-key: raff_pub_yyy

Environment Variables

In addition to the config file, you can override values per-session with environment variables:

Variable	Description
RAFF_API_KEY	API key (--api-key)
RAFF_API_URL	API base URL (--api-url)
RAFF_PROJECT_ID	Default project ID (--project-id)

Precedence: CLI flag > environment variable > profile config file.

Enabling Shell Auto-Completion

raff supports shell tab-completion for commands, subcommands, and flags. Generate a completion script with raff completion <shell>:

raff completion bash       # for bash
raff completion zsh        # for zsh
raff completion fish       # for fish
raff completion powershell # for PowerShell

Linux Auto Completion

The most common way is to source the completion script from your shell config. For bash, add this to ~/.bashrc (or ~/.profile):

source <(raff completion bash)

For zsh, add this to ~/.zshrc:

source <(raff completion zsh)
compdef _raff raff

Then reload:

source ~/.bashrc   # or ~/.zshrc

macOS Auto Completion

macOS users using bash will have to install the bash-completion framework first:

brew install bash-completion

Then add to ~/.bash_profile or ~/.bashrc:

source $(brew --prefix)/etc/bash_completion
source <(raff completion bash)

For zsh on macOS (the default shell since Catalina), add to ~/.zshrc:

autoload -U +X compinit; compinit
source <(raff completion zsh)

Then reload your shell.

Uninstalling raff

If you installed raff by downloading a release archive:

sudo rm /usr/local/bin/raff

If you installed via go install or make install, remove the binary from your Go bin directory:

rm "$(go env GOPATH)/bin/raff"

To completely remove the configuration:

rm -rf ~/.raff

Examples

raff can interact with all Raff resources. Below are common usage examples.

• List all VMs in the current project:

  raff vm list
  

• Create a VM (--pricing-id 9 is the standard 2 vCPU / 4 GB / 50 GB plan at $4.99/mo — see raff pricing vm):

  raff vm create \
    --name web-01 \
    --template-id 5ac21891-32e6-41ce-8a93-b5d6ab708b0d \
    --pricing-id 9 \
    --region us-east \
    --ssh-keys "ssh-ed25519 AAAA..."
  

• Stop, start, reboot a VM:

  raff vm stop <vm-id>
  raff vm start <vm-id>
  raff vm reboot <vm-id>
  

• Resize a VM (change pricing plan or grow disk):

  raff vm resize <vm-id> --pricing-id 5
  raff vm resize-disk <vm-id> --new-size 100
  

• Create a VPC:

  raff vpc create --name prod --cidr 10.0.0.0/20 --region us-east
  

• Reserve a floating IP and attach it to a VM:

  raff ip reserve --type ipv4 --region us-east
  raff vm ip attach <vm-id> --ip-id <ip-id>
  

• Create a security group from a template:

  raff security-group templates                          # list available template IDs
  raff security-group create --name web --template-id web-server
  raff vm sg attach <vm-id> --security-group-id <sg-id> --nic-id 0
  

• Register an SSH key from a file (the typical bootstrap path):

  raff ssh-key create --name laptop --public-key-file ~/.ssh/id_ed25519.pub
  

• Create an API key for CI (secret printed once — copy it immediately):

  raff api-key create --name "production-ci" --rate-limit-tier standard
  

• Invite a teammate to a project:

  raff role list --scope project                            # find the right role UUID
  raff invitation create-project \
    --project-id <project-uuid> \
    --email teammate@example.com \
    --role-id <project-role-uuid>
  

• Add an existing account user to another project:

  raff project member add <project-id> \
    --target-user-id <user-uuid> \
    --role-id <project-role-uuid>
  

• Browse the permission catalog when designing a custom role:

  raff permission list --scope project
  raff role create --name "vm-operator" --slug vm-operator --scope project \
    --permission vm.read --permission vm.start --permission vm.stop
  

• Attach a new volume to a VM at create time:

  raff volume create \
    --name data-vol \
    --size 100 --type nvme --region us-east \
    --vm-id <vm-uuid>
  

• Snapshot a VM before a risky change, restore later:

  raff snapshot create --resource-type vm --resource-id <vm-uuid> --name pre-upgrade
  raff snapshot restore <snapshot-id>      # prompts for confirmation
  

• Set up daily backups on a VM, keep last 14:

  raff backup schedule create \
    --vm-id <vm-uuid> \
    --frequency daily --time 03:00 --keep 14
  

• Browse VM pricing, find the cheapest plan in a region:

  raff pricing vm --region us-east --output json | jq 'min_by(.monthly_price)'
  raff template list --vm-type standard          # all OS templates compatible with the standard VM tier
  raff template list --category marketplace       # pre-baked app images (LAMP, WordPress, …)
  raff template list -o json | jq '.[] | select(.os_type=="linux")'   # filter by OS family (response-side)
  raff region list
  

• JSON output for scripting:

  raff vm list --output json | jq '.[].name'
  

Documentation

• CLI reference — raff <command> --help (every command and flag)
• API reference — docs.rafftechnologies.com
• Dashboard — rafftechnologies.com
• Releases / changelog — github.com/RaffTechnologies/raff-cli/releases

Related projects

• raff-go — official Go SDK that powers this CLI
• terraform-provider-raff — official Terraform provider

Contributing

make build       # build binary to bin/
make test        # run tests
go vet ./...

PRs welcome. Please match the existing command patterns (see internal/commands/ for examples).

License

MIT