CLI for Krova: Cube Commands and Workflow Guide

A CLI (command-line interface) is the fastest way to manage cloud infrastructure when you're already working in your terminal. If you're running AI agent sandboxes, ephemeral CI environments, or self-managed databases, switching between a web dashboard and your editor wastes time and breaks your flow. The Krova command-line interface puts full control over your Cubes, creation, SSH access, port forwarding, snapshots, and automation, into a single tool.

TL;DR:

• A command-line interface lets you create, manage, and connect to Cubes entirely from the terminal.
• The Krova CLI authenticates via OAuth (no key copying), manages Cube lifecycle, and pipes output to scripts and pipelines.
• Use environment variables to automate in CI/CD and headless environments.
• Every command mirrors the REST API, so you can script complex workflows or switch to raw HTTP anytime.

What Is a CLI?

A command-line interface is a text-based way to interact with software. Instead of clicking buttons in a dashboard, you type commands into your terminal. It works over SSH, local files, or HTTP calls to an API, just a different surface for the same underlying operations.

For cloud infrastructure, a CLI shines because it lives where developers already work. You don't alt-tab to a browser tab; you run krova create and move on. The same commands pipe into scripts, CI/CD systems, and other tools. Most infrastructure teams prefer the terminal once they scale beyond one or two servers.

Why a CLI Matters for Cloud Infrastructure

A command-line interface removes friction from your workflow. Say you're developing a Node.js app locally and testing it against a real PostgreSQL database running on a Cube. You can forward a port with krova ssh <cube> -L 5432:localhost:5432, connect your local client, and start debugging without leaving your editor. The same command works in a GitHub Actions runner or container, so your local workflow scales to CI without translation.

A CLI makes automation possible. If you're spinning up fresh Cubes for each AI agent run in a sandbox, a script can call krova create with your snapshot ID, stream logs as the Cube boots, and tear it down when the agent finishes. No dashboard clicking, no manual credential copy-pasting, no race conditions from concurrent provisioning.

A command-line interface integrates with existing tools. Krova's tooling outputs JSON with --json, so you can pipe into jq, feed metrics into monitoring systems, or trigger downstream workflows. It respects shell conventions: exit codes reflect success or failure, and environment variables override flags. This composability is why terminal tools are the backbone of DevOps.

Getting Started with the Krova CLI

Install the CLI. The Krova command-line interface is a pure Node.js package published on npm. Install it globally:

npm install -g @krovacloud/cli

You now have the krova command on your PATH. Verify the install:

krova --version

Authenticate. Every command runs against a context: a named bundle of an API key, a space, and an optional base URL. The CLI stores contexts in ~/.config/krova/config.json with owner-only permissions (0600).

The recommended way is OAuth. Run:

krova login

The CLI opens Krova Cloud in your browser, you approve a short code, and your API key is stored, no copy-pasting secrets. If you already have an API key from your dashboard (Settings → API keys), you can paste it directly:

krova auth set-key <your-api-key>

An API key is scoped to a single space, so the command-line interface resolves your space automatically.

Core CLI Commands for Managing Cubes

Creating a Cube. The most common starting point is provisioning a new Cube. You need a name, an image (Ubuntu, Debian, etc.), and your SSH public key:

krova create --name my-app --image ubuntu-24.04 --ssh-key ~/.ssh/id_ed25519.pub

You can also specify vCPU, RAM, and disk (in GB), which default to 1, 1, and 10:

krova create --name agent-sandbox --image ubuntu-24.04 --ssh-key ~/.ssh/id_ed25519.pub --vcpu 2 --ram 4 --disk 50

The CLI returns the Cube's ID and host.

Connecting via SSH. Once your Cube exists, SSH in with:

krova ssh <cube>

Where <cube> is the name or ID. The command-line interface looks up the host and port from the API and hands off to your system SSH. Your private key stays local; the CLI never sees or transmits it.

Run a command remotely without opening a shell:

krova ssh <cube> -- apt-get update && apt-get install -y postgresql-client

Everything after -- runs as a remote command.

Port forwarding. Forward a service running inside a Cube to your local machine:

krova ssh <cube> -L 5432:localhost:5432

Now localhost:5432 on your machine is an encrypted tunnel to localhost:5432 inside the Cube. Connect your database client and you're live. The -R flag works the same way for reverse tunnels.

Listing and inspecting Cubes. See all Cubes in your current space:

krova list

Get details about a specific Cube:

krova get <cube>

Both work with --json to output structured data for scripts.

Scripting and Automation with Environment Variables

For CI/CD, containers, and headless environments, you don't want interactive login. Configure the CLI entirely from environment variables:

export KROVA_API_KEY="your-api-key"
export KROVA_SPACE_ID="your-space-id"

Now every krova command runs without prompting. You can also use per-command flags (--api-key, --space) if you prefer not to export variables.

For JSON output in scripts, always use --json:

krova list --json | jq '.cubes[] | select(.status == "running")'

This chains with other command-line tools. A timeout flag (--timeout, default 30s) is also global, so slow networks don't block your pipeline.

The command-line interface respects exit codes: zero means success; non-zero means failure. This is how shell scripts and CI systems know whether to proceed or halt.

FAQ

What's the Difference Between the Krova CLI and the REST API?

The CLI is a convenience layer on top of the same REST API. Every command it runs is a plain HTTP call with an X-API-KEY header. If you prefer raw HTTP, code generation, or another language, use the REST API directly. The tool just saves you from writing curl commands by hand.

Can I Use the Krova CLI in a Container or GitHub Actions Runner?

Yes. Set KROVA_API_KEY and KROVA_SPACE_ID as environment variables or secrets, and the command-line interface authenticates without interactive login. The CLI is a pure Node.js package, so it installs in any environment that has npm.

How Do I Automate Cube Creation for AI Agent Sandboxes?

Create a base Cube with your agent runtime installed, then snapshot it with krova snapshot create <cube>. Use the CLI in a loop to spin up fresh copies of that snapshot for each agent run, passing --snapshot-id to krova create. When the agent finishes, tear the Cube down with krova delete <cube>.

What If I Need to Manage Cubes from Claude or Cursor Instead of the Terminal?

The Krova CLI also ships as an MCP (Model Context Protocol) server. Point Claude, Cursor, or any MCP-aware assistant at it, and you can manage your Cubes in conversation. No glue code required.