Layer CLI

The CLI connects to the standalone gateway. Set its base URL to your local service and its key to the gateway bearer token — your Turbopuffer API key.

Install

From the repository root:

go build -o layer ./apps/layer-cli

Configuration

layer reads named environments from ~/.hevlayer/config.toml. The directory is created with mode 0700; the config file is written with mode 0600.

active = "local"

[envs.local]
base_url = "http://localhost:8080"
api_key = "tpuf_..."

Resolution order is:

Priority	Source
1	Explicit flags such as --base-url and --api-key
2	LAYER_BASE_URL, LAYER_API_KEY, and the HEVLAYER_ twins
3	Environment selected by --env or LAYER_ENV
4	Active environment in ~/.hevlayer/config.toml
5	Built-in base URL default

A shell exporting LAYER_BASE_URL or LAYER_API_KEY keeps the env-var-only behavior and does not need a config file. --env and LAYER_ENV select an environment for one invocation without changing the active environment.

Flag	Environment	Default
--base-url	LAYER_BASE_URL, HEVLAYER_BASE_URL	https://aws-us-east-1.hevlayer.com
--api-key	LAYER_API_KEY, HEVLAYER_API_KEY	none
--env	LAYER_ENV	active config env
-o, --output	none	table

Output formats are table, json, and names.

Environments

layer env add local --base-url http://localhost:8080 --api-key "$TURBOPUFFER_API_KEY"
layer env use local
layer env ls
layer env show local -o json

env add prompts for missing values on a TTY. On a non-TTY, the required values must be supplied by flags. API keys are masked in env ls and env show.

Initialize a Namespace

For a Turbopuffer namespace:

layer init products --shards 8
layer init products --shards 8 --watch=false
layer init products --shards 8 --poll-interval 5s

init calls POST /v2/namespaces/{namespace}/init through the selected gateway environment. The command creates or reattaches to the namespace shard marker, starts the shard backfill, and watches by default until shard_lag_rows reaches 0 and scatter/gather is active. Re-running with the same shard count is idempotent; requesting a different shard count returns a conflict message instead of changing the marker.

TUI

The environment and index views read the standalone gateway. Function, pipeline, and key views require the full runtime. Snapshot history columns also require the full runtime.

VectorStores

layer vectorstore list and layer vectorstore get NAME read standalone connection metadata. Configure the connection on the gateway through configuration.

Inspect an index

layer index list and layer index get NAME read namespace metadata. Snapshot-history columns require Pro.

Delete an index

layer index delete NAME requests namespace deletion. For normal local shutdown, use docker compose down.

Ask the docs

From the site/ directory, use pnpm run ask --edition ce search "query". For deployed docs, use layer ask --endpoint https://hevlayer.com/api/ask/ce tree. Full documentation is available at /api/ask/pro.