raff-cli

module

v0.1.1 Latest Latest Go to latest Published: May 9, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/rafftechnologies/raff-cli

Links

Open Source Insights

README ¶

raff

Raff CLI — manage cloud resources from the terminal

Usage:
  raff [command]

Available Commands:
  completion     Generate the autocompletion script for the specified shell
  configure      Configure API credentials and defaults
  help           Help about any command
  ip             Manage floating IPs
  project        Manage projects
  security-group Manage security groups
  vm             Manage virtual machines
  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.

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.1.0 below with the version you want from the Releases page.

# Linux x86_64
curl -sL https://github.com/RaffTechnologies/raff-cli/releases/download/v0.1.0/raff_0.1.0_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.1.0/raff_0.1.0_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:

raff vm create \
  --name web-01 \
  --template-id 5ac21891-32e6-41ce-8a93-b5d6ab708b0d \
  --pricing-id 3 \
  --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

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

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

Directories ¶

Path	Synopsis
cmd
raff command
internal
commands
config
output

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL