CLI operations overview

This is a map of the Volcano building blocks ("elements") the CLI operates on, how they relate, and where the CLI can act on each. Each element has its own page with concrete command examples. For exact, always-current flags, run volcano <command> --help.

The model

A project is the container for everything else. You authenticate, select an active project, then operate on the resources inside it:

account (auth)
├── verified domains .......... domains you own, for custom domains → domains.md
└── project ................... volcano projects / use
    ├── functions ............. deployed backend logic        → functions.md
    │     ├── uses → variables (config & secrets)
    │     ├── connects → databases, storage
    │     ├── runs on → a runtime
    │     ├── invoked via → alias / HTTP / scheduler
    ├── durable functions ..... long-running, checkpointed logic → durable-functions.md
    ├── databases ............. managed Postgres               → databases.md
    │     └── schema changed by → migrations
    ├── storage ............... buckets → objects, policies    → storage.md
    ├── variables ............. env vars / secrets             → variables.md
    ├── frontends ............. deployed sites, custom domains → frontends.md
    ├── git connection ........ push-to-deploy from GitHub     → git.md
    ├── access tokens ......... project-scoped CI credentials  → access-tokens.md
    ├── notifications ......... alerts when schedulers fail    → notifications.md
    ├── LavaFlow .............. diagnoses errors, opens fix PRs → lavaflow.md
    ├── logs .................. search, tail, count runtime logs → logs.md
    └── declarative config .... one YAML syncing the above     → ../project-configuration.md

Cross-cutting concerns:

• Authentication gates all cloud access — see authentication.md.
• Declarative configuration applies settings across every element from one manifest — see project-configuration.md.
• Git connection lets a push deploy the project without a CLI invocation — see git.md.

Local vs. cloud target

The CLI can operate against two targets:

• Local development environment (volcano start / stop / restart / status / reset), targeted by top-level resource commands.
• Cloud project — targeted with the cloud prefix (e.g. volcano cloud functions list).

Top-level resource commands (volcano functions …, volcano durable …, volcano databases …, etc.) always target local development. They fail if the local environment is not running; they do not fall back to cloud. Use the explicit volcano cloud … prefix for cloud operations.

Output styling

Command output is colorized to share one identity with volcano setup: success marks and active states in orange, warnings in amber, errors in red, table headers and titles in lava, and suggested commands in flame. Color is written only to an interactive terminal. It is disabled automatically when output is piped or redirected, in CI, or when NO_COLOR is set, so machine-read output (including --json) stays plain.

volcano databases list          # colorized on a terminal
volcano databases list | cat    # plain (piped)
NO_COLOR=1 volcano databases list

Account credit notices

Cloud commands can report when your account is running low on credits or has no credits left. The notice includes the billing page address when available. Open that page to add credits. These notices do not prompt or open a browser. Piped, CI, and NO_COLOR output remains plain. Machine output is unchanged.

Telemetry

The CLI sends one usage event per command: the command and flag names, the project and resource names it acts on, error messages, CLI version, platform, and which coding agent ran it. Turn it off with volcano telemetry disable or VOLCANO_TELEMETRY_DISABLED=1. See telemetry.md.

Feedback

volcano feedback sends the Volcano team a report about a problem with the CLI, the platform, the docs, or the agent skills. Coding agents run it after a task. Turning telemetry off also turns it off, unless you run volcano feedback enable. Turn it off on its own with volcano feedback disable. See feedback.md.

Element → CLI ability at a glance

Projects

A project owns all resources. Authentication and an active project are prerequisites for cloud operations.

volcano projects create my-app     # create a project
volcano projects list              # list your projects
volcano use my-app                 # set the active project
volcano connect .                  # link this directory to a new project
volcano projects get <project-id>  # project details
volcano projects rename eac37d5a-5f6f-42d8-acf6-0f2ae9c7a550 new-name  # rename a project
volcano projects keys anon list    # anon (publishable) API keys for the browser/SDK
volcano projects keys service list # backend service-key metadata for the active project
volcano projects usage             # current-month and all-time usage totals
volcano projects delete my-app     # delete

When your account has no projects, volcano projects list says so and suggests volcano projects create <name>.

Inside a directory linked with volcano connect, commands use the linked project. See connect.md.

Create a project from a cloud template

Use --template to install a complete app in a new cloud project:

volcano projects create my-board --template trellini
volcano projects create my-pixels --template pixel-board
volcano projects create my-pad --template collab-pad

The supported templates are trellini, pixel-board, and collab-pad. An account token is required. Hosting creates a fresh database and deploys the app's functions and frontends. These cloud installations do not write local starter files like volcano init.

Installation runs asynchronously. Project creation does not mean the app is ready. Use the project ID printed by the create command to check progress:

volcano projects get <project-id>

Project details show the template status (pending, running, ready, or failed) and phase (database, restore, configure, deploy, verify, or ready). Wait for template status ready before using the app. If installation fails, the project remains available for inspection or deletion:

volcano projects delete <project-id>

Project details

volcano projects list and volcano projects get show the project plan as HOBBY or SUPERAGENT when the API provides it.

VOLCANO_PROJECT_ID overrides the active project for a single invocation. It is deprecated and will be removed in a future release, and a command that uses it prints a warning on stderr. Select the project with volcano use <project-id>, or volcano login --token <token> --project <project-id> in CI. See access-tokens.md.

Project keys

volcano projects keys requires an explicit key type. volcano projects keys anon list [project-id] lists publishable anon keys. volcano projects keys anon create <name> [project-id] creates a publishable auth-only key using the server default.

Backend service keys

Service keys are privileged backend credentials that bypass row-level security. Never expose their values in frontend code, logs, shell history, or other untrusted output. list and get show metadata by default. Use --show-key only when you need the plaintext. create prints the new key; use --json to script it:

volcano projects keys service list --page 1 --limit 100
volcano projects keys service create worker --permission functions.invoke --json
volcano projects keys service get <key-id> --show-key

--permission is repeatable; --permissions is an equivalent spelling and the two can be combined. Omitting both gives the key full access. Empty or blank permission values are rejected so an intended restricted key cannot silently fall back to full access.

An explicit [project-id] takes precedence over the active project. Without it, the deprecated VOLCANO_PROJECT_ID takes precedence over the active project. Paginated list output includes a next-page command that retains an explicit project ID.

Project usage

volcano projects usage [project-id] prints each metric's current-month total and all-time total. It does not print the hourly or daily time series returned by the API. Project selection follows the same explicit ID, environment, then active-project precedence described above.

Starting a project

volcano init javascript            # scaffold a local project (js/nextjs/python/ruby)
volcano start                      # start the local dev environment
volcano status                     # check it
volcano deploy --with-migrations   # deploy the whole project to it

See deploy.md for what volcano deploy and volcano cloud deploy read and the order they deploy in.

volcano start runs the local stack from a bundled default server image. Override it with --image or VOLCANO_IMAGE; an explicitly selected image must already exist locally, since the CLI never pulls an unpublished local-mode image.

volcano start --image kong/volcano:local-nightly
VOLCANO_IMAGE=kong/volcano:local-nightly volcano start

• Sandboxes: isolated commands, sessions, files, and templates.