# 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.

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:

```text
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](https://docs.volcano.dev/cli/authentication.md).
- **Declarative configuration** applies settings across every element from one
  manifest — see [project-configuration.md](https://docs.volcano.dev/cli/project-configuration.md).
- **Git connection** lets a push deploy the project without a CLI invocation —
  see [git.md](https://docs.volcano.dev/cli/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.

```bash
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](https://docs.volcano.dev/cli/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](https://docs.volcano.dev/cli/feedback.md).

## Element → CLI ability at a glance

| Element | CLI can… | Commands | Details |
|---|---|---|---|
| Get started | sign in, create a project, and link a directory in one step | `connect` | [connect.md](https://docs.volcano.dev/cli/connect.md) |
| Account / auth | sign up, log in/out | `signup`, `login`, `logout` | [authentication.md](https://docs.volcano.dev/cli/authentication.md) |
| Access tokens | create, list, get, revoke project credentials | `cloud access-tokens …` | [access-tokens.md](https://docs.volcano.dev/cli/access-tokens.md) |
| Project | create, list, get, rename, delete, select, get keys and usage | `projects …`, `use` | below |
| Whole project | deploy variables, migrations, functions, frontends, and config in one run | `deploy`, `cloud deploy` | [deploy.md](https://docs.volcano.dev/cli/deploy.md) |
| Deployments | list, inspect and summarize every function and frontend deployment | `deployments …`, `cloud deployments …` | [deployments.md](https://docs.volcano.dev/cli/deployments.md) |
| Logs | search, tail and count logs across functions, frontends and databases | `logs …`, `cloud logs …` | [logs.md](https://docs.volcano.dev/cli/logs.md) |
| Functions | deploy, invoke, inspect, set visibility, schedule, alias | `functions …` | [functions.md](https://docs.volcano.dev/cli/functions.md) |
| Durable functions | deploy, start, inspect executions, read logs, schedule, decide approvals, send and read messages, answer callbacks | `durable …`, `cloud durable …` | [durable-functions.md](https://docs.volcano.dev/cli/durable-functions.md) |
| Databases | create, inspect, delete, migrate | `databases …`, `migrations …` | [databases.md](https://docs.volcano.dev/cli/databases.md) |
| Storage | manage buckets, objects, policies | `storage …` | [storage.md](https://docs.volcano.dev/cli/storage.md) |
| Variables | deploy, list, get, delete | `variables …` | [variables.md](https://docs.volcano.dev/cli/variables.md) |
| Notifications | alert by email or webhook when schedulers fail, rotate the webhook secret, send a test | `notifications …`, `cloud notifications …` | [notifications.md](https://docs.volcano.dev/cli/notifications.md) |
| LavaFlow | turn on or off, set how far it goes, see stats and runs with their diagnoses | `cloud lavaflow …` | [lavaflow.md](https://docs.volcano.dev/cli/lavaflow.md) |
| Frontends | deploy, inspect, custom domains, function and Frontend routes | `frontends …`, `cloud frontends …` | [frontends.md](https://docs.volcano.dev/cli/frontends.md) |
| Config (declarative) | deploy/pull one YAML manifest | `config deploy`, `config pull` | [project-configuration.md](https://docs.volcano.dev/cli/project-configuration.md) |
| Local environment | check prerequisites, start/stop/status/reset | `doctor`, `start`, `stop`, `restart`, `status`, `reset` | above |
| Coding agents | install Volcano skills/plugins, keep them current | `setup` | [setup.md](https://docs.volcano.dev/cli/setup.md) |
| Documentation | search/read the docs | `docs …` | [docs-search.md](https://docs.volcano.dev/cli/docs-search.md) |
| Scripts and agents | exit codes, JSON output | `--json` | [scripting.md](https://docs.volcano.dev/cli/scripting.md) |

## Projects

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

```bash
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](https://docs.volcano.dev/cli/connect.md#linked-directories).

### Create a project from a cloud template

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

```bash
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:

```bash
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:

```bash
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](https://docs.volcano.dev/cli/access-tokens.md#use-a-token).

### 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:

```bash
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

```bash
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](https://docs.volcano.dev/cli/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.

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

- [Sandboxes](https://docs.volcano.dev/cli/sandboxes.md): isolated commands, sessions, files, and templates.