ionosctl

The command-line interface for IONOS Cloud. Create and manage cloud resources -- virtual machines, networks, storage, databases, Kubernetes clusters, DNS, and more -- directly from your terminal.

ionosctl-usage.webm

Prerequisites: You need an IONOS Cloud account to use ionosctl.

Quick Start

# 1. Install (macOS example -- see Installation for all platforms)
brew tap ionos-cloud/homebrew-ionos-cloud && brew install ionosctl

# 2. Authenticate
ionosctl login

# 3. Verify your identity
ionosctl cfg whoami

# 4. Run your first command
ionosctl datacenter list

# 5. Explore available commands
ionosctl --help

Installation

macOS (Homebrew)

brew tap ionos-cloud/homebrew-ionos-cloud
brew install ionosctl

Linux (Snap)

snap install ionosctl

Windows (Scoop)

scoop bucket add ionos-cloud https://github.com/ionos-cloud/scoop-bucket.git
scoop install ionos-cloud/ionosctl

Binary Download

Download the archive for your OS and architecture from the Releases page, or use:

# Download and extract (replace <version> with the full semantic version)
curl -sL https://github.com/ionos-cloud/ionosctl/releases/download/v<version>/ionosctl-<version>-linux-amd64.tar.gz | tar -xzv

# Move to a directory in your PATH
sudo mv ionosctl /usr/local/bin/

# Verify
ionosctl version

Building from Source

Requires Go (see go.mod for minimum version).

git clone https://github.com/ionos-cloud/ionosctl.git
cd ionosctl
make build    # or: make install

Dependencies are managed with Go Modules and vendored.

Note: The development version may contain unreleased changes. For production use, prefer official releases.

Authentication

ionosctl supports multiple authentication methods. Environment variables take priority over the config file.

Token Authentication

Token-based authentication is the recommended approach, especially for accounts with two-factor authentication (2FA) enabled:

# Via environment variable
export IONOS_TOKEN="your-bearer-token"

# Or via login command (persists to config file)
ionosctl login --token "$IONOS_TOKEN"

You can create tokens via the DCD or the CLI (ionosctl token create).

Username & Password

For accounts without 2FA, username/password authentication is also supported:

# Interactive login (prompts securely for credentials)
ionosctl login

# Or via environment variables
export IONOS_USERNAME="your-email@example.com"
export IONOS_PASSWORD="your-password"

Verifying Your Identity

Use whoami to check who you're logged in as, and --provenance to debug the authentication source:

ionosctl cfg whoami
ionosctl cfg whoami --provenance

Usage

Command Structure

ionosctl [service] [resource] [command] [flags]

Examples:

# List all data centers
ionosctl datacenter list

# Create a server in a data center
ionosctl server create --datacenter-id <dc-id> --name "web-server" --cores 2 --ram 4096

# Get a specific resource as JSON
ionosctl server get --datacenter-id <dc-id> --server-id <server-id> --output json

# Delete with auto-confirm (useful for scripts)
ionosctl server delete --datacenter-id <dc-id> --server-id <server-id> --force

# List Kubernetes clusters
ionosctl k8s cluster list

# Create a DNS zone
ionosctl dns zone create --name example.com

# List PostgreSQL clusters
ionosctl dbaas postgres cluster list

Interactive Shell

ionosctl includes a built-in interactive shell with auto-completion, command history, and inline suggestions -- ideal for exploration and ad-hoc management:

ionosctl shell

Inside the shell, you get:

Real-time auto-completion for commands, subcommands, and flags
Keyboard shortcuts (Ctrl+A/E for line start/end, Ctrl+P/N for history, Ctrl+W to cut word, etc.)
Persistent flag values between commands with --persist-flag-values

Note: The interactive shell is a BETA feature. Destructive commands (e.g., delete) require the --force flag instead of interactive confirmation.

Output Formats

Control how results are displayed with --output (-o):

Format	Flag	Description
Table (default)	`--output text`	Human-readable tabular output
JSON	`--output json`	Parsed JSON, suitable for `jq` piping
API JSON	`--output api-json`	Raw API response JSON

# Default table output
ionosctl datacenter list
# DatacenterId                          Name         Location
# 12345678-abcd-1234-abcd-123456789012  production   de/fra

# JSON output
ionosctl datacenter list --output json
# [{"id": "12345678-...", "properties": {"name": "production", ...}}]

# Select specific columns
ionosctl datacenter list --cols "DatacenterId,Name,Location"

# Hide column headers (useful for scripting)
ionosctl datacenter list --no-headers

# Quiet mode -- suppress all output except errors
ionosctl server delete --datacenter-id <id> --server-id <id> --force --quiet

Filtering & Querying

# Server-side filtering on list commands
ionosctl datacenter list --filters "name=production"
ionosctl server list --datacenter-id <id> --filters "vmState=RUNNING,cores=4"

# Order results
ionosctl datacenter list --order-by name

# Pagination
ionosctl server list --datacenter-id <id> --limit 10 --offset 20

# JMESPath query for advanced output filtering
ionosctl datacenter list --output json --query "[?properties.location=='de/fra']"

# Control API response depth
ionosctl datacenter get --datacenter-id <id> --depth 3

Waiting for Resources

Many create/update/delete operations return immediately while the resource is being provisioned. ionosctl commands that modify resources typically support a --wait-for-request (-w) flag to block until the operation completes:

# Wait for server to be fully provisioned
ionosctl server create --datacenter-id <id> --name "my-server" --cores 2 --ram 4096 --wait-for-request

# Wait for deletion to complete
ionosctl server delete --datacenter-id <id> --server-id <id> --force --wait-for-request

Scripting & Automation

ionosctl is designed to work well in scripts and CI/CD pipelines:

# Use JSON output + jq for programmatic access
DC_ID=$(ionosctl datacenter list --output json | jq -r '.[0].id')

# Combine --force and --wait-for-request for unattended operations
ionosctl server delete --datacenter-id "$DC_ID" --server-id "$SRV_ID" --force --wait-for-request

# Use --quiet to suppress output in scripts (only errors go to stderr)
ionosctl volume create --datacenter-id "$DC_ID" --name "data" --size 50 --quiet --wait-for-request

# Delete all servers in a datacenter
ionosctl server delete --datacenter-id "$DC_ID" --all --force

# Use --no-headers and --cols for clean parseable output
ionosctl server list --datacenter-id "$DC_ID" --cols ServerId --no-headers

Getting Help

# Top-level help
ionosctl --help

# Help for a specific command
ionosctl server create --help

# Help for a service group
ionosctl dbaas --help

# Nested help
ionosctl k8s cluster --help

Global Flags

These flags are available on all (or most) commands:

Flag	Short	Description
`--output`	`-o`	Output format: `text`, `json`, `api-json`
`--quiet`	`-q`	Suppress all output except errors
`--force`	`-f`	Skip confirmation prompts (for destructive commands)
`--all`	`-a`	Target all resources (for delete/remove commands)
`--wait-for-request`	`-w`	Block until the API operation completes
`--verbose`	`-v`	Increase verbosity (`-v`, `-vv`, `-vvv`)
`--no-headers`		Hide table column headers
`--cols`		Select specific output columns
`--filters`	`-F`	Server-side filtering (`KEY=VALUE,...`)
`--order-by`		Sort results by property
`--limit`		Max items per request (default: 50)
`--offset`		Skip N items for pagination
`--query`		JMESPath query to filter output
`--depth`	`-D`	API response detail level (default: 1)
`--api-url`	`-u`	Override API endpoint
`--config`		Path to config file

Shell Auto-Completion

ionosctl supports auto-completion for Bash, Zsh, Fish, and PowerShell. Completions include commands, subcommands, flags, and even flag values (like available data center IDs).

Bash

# Current session
source <(ionosctl completion bash)

# Permanent (add to ~/.bashrc)
echo 'source <(ionosctl completion bash)' >> ~/.bashrc

Zsh

# Setup (add to ~/.zshrc BEFORE compinit)
mkdir -p ~/.config/ionosctl/completion/zsh
ionosctl completion zsh > ~/.config/ionosctl/completion/zsh/_ionosctl

Add to ~/.zshrc:

fpath+=(~/.config/ionosctl/completion/zsh)
autoload -Uz compinit; compinit

Fish

ionosctl completion fish > ~/.config/fish/completions/ionosctl.fish

PowerShell

# Current session
ionosctl completion powershell | Out-String | Invoke-Expression

# Permanent (add to your PowerShell profile)
ionosctl completion powershell > ionosctl.ps1
# Then source it from your $PROFILE

Tip: Use --no-descriptions to disable completion descriptions if your shell feels too cluttered.

Configuration

ionosctl login generates a YAML config file that stores your token and per-product API endpoint URLs (auto-discovered from the IONOS Cloud API index). Default location:

OS	Path
macOS	`~/Library/Application Support/ionosctl/config.yaml`
Linux	`$XDG_CONFIG_HOME/ionosctl/config.yaml`
Windows	`%APPDATA%\ionosctl\config.yaml`

ionosctl cfg location      # Print config file path
ionosctl cfg whoami        # Show current identity and auth source
ionosctl cfg logout        # Clear credentials (keeps endpoint URLs)
ionosctl login --example   # Preview the generated YAML without writing it

You can use --config /path/to/config.yaml to point to a different config file, and --profile-name / --environment during login to set up multiple profiles.

Authentication priority: env IONOS_TOKEN > env IONOS_USERNAME/IONOS_PASSWORD > config file token > config file username/password. Use ionosctl cfg whoami --provenance to see which source is active.

API URL priority: --api-url flag > IONOS_API_URL env var > per-product endpoint in config file > built-in default. This lets the config file hold per-product overrides (e.g., for staging) while flags and env vars can override on the fly.

Environment Variables

Variable	Description
`IONOS_USERNAME`	Username for basic authentication
`IONOS_PASSWORD`	Password for basic authentication
`IONOS_TOKEN`	Bearer token (takes precedence over username/password)
`IONOS_API_URL`	Override the default API endpoint (`api.ionos.com`)
`IONOS_LOG_LEVEL`	SDK log level: `Off`, `Debug`, `Trace`
`IONOS_PINNED_CERT`	SHA-256 fingerprint for certificate pinning

Warning: Set IONOS_LOG_LEVEL=Trace only for debugging. It logs full request/response payloads including sensitive data, and can significantly impact performance.

Advanced Configuration

Certificate Pinning

Bypass standard certificate validation by pinning a specific SHA-256 fingerprint (useful for self-signed certificates):

export IONOS_PINNED_CERT="<sha256-public-fingerprint>"

You can obtain the SHA-256 fingerprint from your browser's certificate inspector.

Man Pages (Linux)

Generate man pages for offline reference:

ionosctl man --target-dir /tmp/ionosctl-man
# Then copy to your man path and run: sudo mandb

Checking for Updates

ionosctl version --updates

Documentation

Resource	Link
Full CLI Reference	docs.ionos.com/cli-ionosctl
IONOS Cloud User Guide	docs.ionos.com/cloud
API Reference	api.ionos.com/docs
Cloud Console (DCD)	dcd.ionos.com
Changelog	CHANGELOG.md

Uninstalling

# Homebrew (macOS)
brew uninstall ionosctl

# Snap (Linux)
snap remove ionosctl

# Scoop (Windows)
scoop uninstall ionosctl

# Manual install
sudo rm /usr/local/bin/ionosctl

# Local build
make clean

Contributing

Bugs & feature requests: Open an issue

Pull requests are welcome! Fork the repository, make your changes, and submit a PR. We'll review it and work together to get it released.

Running Tests

make test

Name		Name	Last commit message	Last commit date
Latest commit History 586 Commits
.github		.github
commands		commands
docs		docs
internal		internal
pkg		pkg
services/cloudapi-v6		services/cloudapi-v6
snap		snap
test		test
tools		tools
vendor		vendor
.gitbook.yaml		.gitbook.yaml
.gitignore		.gitignore
.gitmodules		.gitmodules
.goreleaser.yml		.goreleaser.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
sonar-project.properties		sonar-project.properties

Folders and files

Latest commit

History

Repository files navigation

ionosctl

Table of Contents

Quick Start

Installation

macOS (Homebrew)

Linux (Snap)

Windows (Scoop)

Binary Download

Building from Source

Authentication

Token Authentication

Username & Password

Verifying Your Identity

Usage

Command Structure

Interactive Shell

Output Formats

Filtering & Querying

Waiting for Resources

Scripting & Automation

Getting Help

Global Flags

Shell Auto-Completion

Bash

Zsh

Fish

PowerShell

Configuration

Environment Variables

Advanced Configuration

Certificate Pinning

Man Pages (Linux)

Checking for Updates

Documentation

Uninstalling

Contributing

Running Tests

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 82

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages