HelixDB Docs

Reference

Create and manage service credentials: workspace-owned secrets that let headless automation call Helix Cloud. You manage them with your WorkOS login, but they never log the CLI in. Cloud only. Owners and admins need the workspace-scoped service_credentials.manage permission.

Usage

helix service-credential create --name <name> \
  --grant <project-id>=project-read,query-read [--expires-at <RFC3339>]
helix service-credential [list]
helix service-credential get <CREDENTIAL>
helix service-credential update <CREDENTIAL> \
  [--name <name>] [--grant <project-id>=query-read,query-write] \
  [--expires-at <RFC3339> | --clear-expiry]
helix service-credential revoke <CREDENTIAL> [--yes]

Every subcommand also accepts --workspace.

Subcommands

Subcommand	Description
`create`	Create a credential and print its secret once.
`list`	List credentials owned by a workspace. The default when no subcommand is given.
`get`	Show one credential. Its secret is never returned.
`update`	Change the name, expiry, or project grants without rotating the secret.
`revoke`	Revoke a credential.

Arguments

Argument	Description
`CREDENTIAL`	Credential ID or name to act on with `get`, `update`, or `revoke`. Required.

Options

Flag	Description	Default
`--workspace <WORKSPACE>`	Owning workspace ID, slug, or name.	Linked workspace, then the only workspace
`--name <NAME>`	Credential name. Required for `create`; renames on `update`.	—
`--grant <PROJECT_ID>=<PERMISSIONS>`	Project grant, repeatable. `create` needs at least one; on `update`, any `--grant` replaces all existing grants.	—
`--expires-at <RFC3339>`	Expiry time for `create` or `update`.	No expiry
`--clear-expiry`	`update`: remove the expiry. Conflicts with `--expires-at`.	Off
`-y`, `--yes`	`revoke`: skip the confirmation prompt. Required without a terminal or with `--json`.	Off
`--json`	Print the result as JSON on stdout and never prompt.	Off

Behavior

The workspace resolves as described in Cloud resource resolution.
Each grant is project-scoped and must name a project ID inside the owning workspace.
Available grants are project-read, project-write, query-read, and query-write, comma-separated; write requires its matching read.
Each project may appear in only one --grant, and a grant cannot repeat a permission.
Creation prints the secret once on stdout. With --json, the full create response, including the secret, is printed instead. Updates never reveal or rotate it.
update needs at least one of --name, --grant, --expires-at, or --clear-expiry.
revoke asks for confirmation in a terminal. Without one, or with --json, it fails before any request unless you pass --yes.
Service credentials authenticate headless HTTP API calls and the unified MCP endpoint at https://mcp.helix-db.com/mcp.
MCP exposes only the query and customer administration tools their project grants allow. These sessions do not get Cloud discovery or observability tools.
They are never a CLI login method and the CLI never persists them.

Examples

# Create a read-only credential for one project, expiring at the end of the year
helix service-credential create --name ci-reader \
  --grant <project-id>=project-read,query-read --expires-at 2026-12-31T23:59:59Z

# Allow the credential to write queries too (replaces all grants)
helix service-credential update ci-reader \
  --grant <project-id>=project-read,query-read,query-write

# Revoke it without a prompt
helix service-credential revoke ci-reader --yes

helix auth — the WorkOS login used to manage credentials.
helix workspace — list your workspaces.
helix project — find the project IDs to grant.

Using the helix CLI

CLI Command Reference

helix service-credential

Usage

Subcommands

Arguments

Options

Behavior

Examples

​Usage

​Subcommands

​Arguments

​Options

​Behavior

​Examples

​Related

Usage

Subcommands

Arguments

Options

Behavior

Examples

Related