> ## Documentation Index
> Fetch the complete documentation index at: https://helix-isolate-failing-index-entities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI command reference

> Every Helix CLI command, grouped by what it manages

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

Every `helix` command, grouped the same way as `helix --help`. **Scope** shows whether a command
works with local instances, Helix Cloud, or both.

Cloud commands authenticate only with the WorkOS session created by `helix auth login`.
They never accept or store application database keys or service credentials.

## Getting started

| Command | Scope | Purpose |
| - | - | - |
| [`helix chef`](/cli/command-reference/chef) | Local | Bootstrap a first app with a coding agent (alias: `cook`) |
| [`helix init`](/cli/command-reference/init) | Local, Cloud | Create a project and link an instance |
| [`helix add`](/cli/command-reference/add) | Local, Cloud | Add an instance to `helix.toml` |

## Instances and queries

| Command | Scope | Purpose |
| - | - | - |
| [`helix start`](/cli/command-reference/start) | Local | Start a local instance in the background (alias: `run`) |
| [`helix stop`](/cli/command-reference/stop) | Local | Stop a local instance and remove its containers |
| [`helix restart`](/cli/command-reference/restart) | Local | Restart a local instance |
| [`helix status`](/cli/command-reference/status) | Local, Cloud | Inspect runtime or database status |
| [`helix logs`](/cli/command-reference/logs) | Local, Cloud | Follow local logs or list Cloud query errors |
| [`helix query`](/cli/command-reference/query) | Local, Cloud | Execute one v3 JSON/SDK query |
| [`helix shell`](/cli/command-reference/shell) | Local, Cloud | Execute line-oriented v3 JSON queries |
| [`helix prune`](/cli/command-reference/prune) | Local | Remove Helix-owned local containers, volumes, and state |
| [`helix delete`](/cli/command-reference/delete) | Local, Cloud | Remove an instance from `helix.toml` and clean up its local state |

## Helix Cloud

| Command | Scope | Purpose |
| - | - | - |
| [`helix auth`](/cli/command-reference/auth) | Cloud | Log in, inspect, or revoke the WorkOS session |
| [`helix workspace`](/cli/command-reference/workspace) | Cloud | List or get workspaces; no global selection |
| [`helix project`](/cli/command-reference/project) | Cloud | List, get, create, delete, or link a project |
| [`helix cluster`](/cli/command-reference/cluster) | Cloud | List or get clusters and their active indexes |
| [`helix database`](/cli/command-reference/database) | Cloud | Manage tenants, indexes, and application keys |
| [`helix service-credential`](/cli/command-reference/service-credential) | Cloud | Manage workspace-owned headless credentials |
| [`helix api`](/cli/command-reference/api) | Cloud | Call an authenticated `/v1/...` Helix Cloud API endpoint |

## CLI utilities

| Command | Scope | Purpose |
| - | - | - |
| [`helix skills`](/cli/command-reference/skills) | CLI | Install, update, and list the Helix agent skills |
| [`helix metrics`](/cli/command-reference/metrics) | CLI | Configure CLI telemetry collection |
| [`helix update`](/cli/command-reference/update) | CLI | Update the CLI to the latest version |
| [`helix feedback`](/cli/command-reference/feedback) | CLI | Open a pre-filled feedback issue on GitHub |

## Global options

These flags work with every command.

| Flag | Description |
| - | - |
| `--json` | Print the result as compact JSON on stdout, print nothing else, and never prompt. Conflicts with `--quiet` and `--verbose`. |
| `--quiet` | Errors and final result only. |
| `-v`, `--verbose` | Detailed output with timing information. |
| `-h`, `--help` | Show help. `helix <command> --help` shows that command's options. |
| `-V`, `--version` | Show the CLI version. |

## Output

* stdout carries only the command's result: tables, detail views, query results, one-time tokens, or the `--json` payload. It is always safe to pipe.
* stderr carries everything else: progress sessions, spinners, warnings, hints, and errors.
* Destructive Cloud commands (`project delete`, `database delete`, `database key revoke`, `service-credential revoke`) ask for confirmation in a terminal. Without one, or with `--json`, they fail before any request unless you pass `-y`/`--yes`. They never act on an "only candidate" they were not told about: the target must be named, linked in `helix.toml`, or picked in a terminal.
* Commands whose output is a live terminal session have no JSON result and refuse `--json`: `chef`, `start --foreground`, local `logs`, and `skills install` / `skills list`.

With `--json`, a failed command prints one JSON object on stderr and exits with status `1`, or `2`
for invalid arguments. Only `message` is always present:

```json theme={null}
{"error":{"message":"...","context":"...","caused_by":"...","hint":"...","candidates":[{"id":"...","name":"..."}]}}
```

## Cloud resource resolution

Cloud commands never require raw IDs. Workspace, project, cluster, and database arguments are
optional and accept an ID, slug, or display name, matched in that order (names are
case-insensitive). Databases also accept `tenant:<id>` and `cluster:<id>`. Application keys and
service credentials are passed by ID or name.

An omitted resource resolves to:

1. the project or databases linked in `helix.toml`;
2. the only candidate, announced on stderr (for example `Using project <name>`);
3. an interactive picker, in a terminal and without `--json`;
4. otherwise, an error that lists the candidates and how to pass one.

A name you pass that matches more than one resource is always an error listing the matches, even in
a terminal; pickers only fill in arguments you left out. A resource passed by ID or as
`tenant:<id>` / `cluster:<id>` must belong to any `--project` / `--workspace` you also pass, so
`helix database delete tenant:<id> --project <other>` fails instead of acting outside that project.

`--json` output is the server's JSON, field for field. Where the human view shows a resolved owner
(for example the workspace of a project found in a listing), `--json` does not add it.

There is no global or persisted workspace or project selection. A group run without a subcommand
lists its resources, so `helix project` is the same as `helix project list`. Lists follow API
pagination.

## Removed and unsupported commands

`push`, `sync`, `config`, `auth create-key`, `workspace switch`, and `project update` are not commands.
`compile`, `check`, and `deploy` were removed; running them prints a pointer to the current workflow.
`--format` and `--compact` were replaced by `--json`; the inline request body of `helix query` and
`helix api` is now `--body`. `--workspace-id`, `--project-id`, and `--cluster-id` were replaced by
the resolution above, and `helix logs --range` by plain `--start`/`--end`. Cloud resource lifecycle
is exposed only where documented above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.