CLI Reference

The Crate CLI is a universal tool for interacting with the Crate ecosystem. It provides a seamless developer experience for managing secrets securely and validating your gateway configurations before deployment.

Prerequisites

Before using the secrets commands, ensure you are authenticated and have an active organization session:

crate login
crate session org set <organization-id>

Gateway Configuration

crate gateway config validate

Validates a declarative infrastructure configuration file (e.g. crate.yml) against the official schema. This is highly recommended before deploying new routing rules or plugins to production.

# Validates the specified file
crate gateway config validate ./config.prod.yaml

# Run interactively (prompts for a file)
crate gateway config validate

Tag Management

Manage tags used to categorize secrets and other resources across your organization.

crate tags list

Lists all tags created within your organization, along with any metadata like color or description.

crate tags list --org <organization-id>

Secrets Management

All crate secrets commands support the following persistent flags:

Commands

crate secrets list

Lists the names of all secrets in the specified environment. This command does not return the secret values, only metadata.

crate secrets list --env prod

crate secrets set

Stores or updates a secret.

Security Note: This command uses Sealed Transport. The CLI fetches your organization’s public RSA key, encrypts the secret value locally, and sends the ciphertext to the server. The plaintext value never leaves your machine.

You can also use the --tags flag to categorize secrets for easier fetching later.

# Provide arguments directly with tags
crate secrets set DATABASE_URL postgres://user:pass@localhost:5432/db --env staging --tags backend,db

# Or run interactively (input will be masked)
crate secrets set

crate secrets get

Retrieves and decrypts a single secret’s value.

crate secrets get STRIPE_API_KEY --env dev

Output: STRIPE_API_KEY=sk_test_12345

crate secrets delete

Permanently deletes a secret. This action cannot be undone. If run without arguments, you will be prompted to select a secret interactively.

crate secrets delete STRIPE_API_KEY --env dev

crate secrets fetch

Securely retrieves multiple secrets at once. Uses an ephemeral RSA key exchange to ensure the secrets cannot be intercepted in transit.

# Fetch all secrets in the environment
crate secrets fetch --all --env dev

# Fetch specific secrets by name
crate secrets fetch --names=DATABASE_URL,REDIS_URL --env prod

# Fetch secrets by tag
crate secrets fetch --tags=backend --env dev

crate run

Executes a child process and injects your secrets as environment variables. This is the recommended way to use secrets in local development and CI/CD pipelines.

crate run --env dev -- go run main.go

If the Crate API is unreachable, crate run can fallback to loading secrets from a local .env file using the --env-file flag.