Skip to main content

CLI Reference

title: CLI Reference audience: Developer difficulty: Intermediate estimated_read_time: 5 min prerequisites:

  • CLI installed
  • Basic terminal usage related_pages:
  • ../getting-started/installation.md
  • ../api-reference/index.md

Complete command reference for the envcat CLI tool.

Overview​

The envcat CLI is a Go binary that enables device-approval flow for requesting environment variables from env.cat.

Key features:

  • Device-approval flow: OAuth-style approval in browser
  • End-to-end encryption: Ephemeral keypairs, sealed boxes
  • Shell-safe output: Works with bash, zsh, fish, and .env files
  • Cross-platform: Linux, macOS (ARM64 + AMD64)

Installation​

One-line installer (recommended):

curl -fsSL https://env.cat/cli/install.sh | sh

Manual installation:

Verify installation:

envcat --version

See: Installation Guide for detailed instructions.

Global Usage​

constants [command] [flags]

Global Flags​

Available on all commands:

FlagTypeDefaultDescription
--api-basestringhttps://env.catAPI base URL
--helpbooleanfalseShow help

Commands​

envcat get​

Request environment variables using device-approval flow.

→ Complete reference

Synopsis:

envcat get [flags]

Key flags:

  • --api-base - API URL (default: https://env.cat)
  • --bundle - Bundle ID or name
  • --keys - Specific keys to request (comma-separated)
  • --format - Output format: sh, fish, .env (default: sh)
  • --write / --file - Write to file instead of stdout

Example:

# Request all keys from bundle
envcat get --bundle dev/api

# Request specific keys
envcat get --bundle dev/api --keys DATABASE_URL,API_KEY

# Write to .env file
envcat get --bundle dev/api --file .env

# Fish shell format
envcat get --bundle dev/api --format fish | source

Usage:

# Inject into current shell (bash/zsh)
eval "$(envcat get --bundle dev/api)"

# Or save to .env
envcat get --bundle dev/api --file .env

Output Formats​

Shell (default)​

Format: sh (bash, zsh compatible)

export KEY=value
export SPACEY='hello world'
export QUOTED='He said "hi"'

Usage:

eval "$(envcat get)"

Fish Shell​

Format: fish

set -x KEY value
set -x SPACEY 'hello world'

Usage:

envcat get --format fish | source

.env File​

Format: .env (dotenv compatible)

KEY=value
SPACEY="hello world"
QUOTED="He said \"hi\""

Usage:

envcat get --write .env
source .env  # or use with dotenv tools

Quoting Behavior​

The CLI handles all edge cases safely:

ValueShell Output.env Output
hello world'hello world'"hello world"
cost is $5'cost is $5'"cost is $5"
He said "hi"'He said "hi"'"He said \"hi\""
value with # hash'value with # hash'"value with # hash"
multi\nline'multi\nline'"multi\\nline"

Shell quoting rules:

  • Simple values: No quotes
  • Spaces, special chars: Single quotes
  • Single quotes in value: Escaped with '"'"'

.env quoting rules:

  • Always double quotes
  • Escape internal double quotes with \
  • Newlines: Literal \n

Environment Variables​

CLI behavior can be configured via environment variables:

VariableDescriptionDefault
ENVCAT_API_BASEAPI base URLhttps://env.cat
ENVCAT_FORMATDefault output formatsh
ENVCAT_BUNDLEDefault bundle(none)

Example:

export ENVCAT_API_BASE=https://env.cat
export ENVCAT_FORMAT=fish
envcat get  # Uses env vars

Exit Codes​

CodeMeaning
0Success
1General error
2Invalid arguments
3Network error (API unreachable)
4Request expired or not found
5Approval rejected or timed out

Example:

if envcat get --bundle dev/example; then
  echo "Success"
else
  echo "Failed with code $?"
fi

Examples​

Basic Usage​

# Request secrets
envcat get --bundle dev/myproject

# CLI displays QR and URL, waits for approval
# After approval, outputs exports

Scripting​

#!/bin/bash
set -e

# Load secrets into shell
eval "$(envcat get --bundle dev/myproject)"

# Use secrets
echo "API Key: $API_KEY"
psql $DB_URL

CI/CD​

# In GitHub Actions, GitLab CI, etc.
- name: Load secrets
  run: |
    envcat get --bundle ci/project --write .env
    source .env
    npm test

Multi-Environment​

# Development
eval "$(envcat get --bundle dev/myproject)"

# Staging
eval "$(envcat get --bundle staging/myproject)"

# Production (be careful!)
eval "$(envcat get --bundle prod/myproject)"

Per-Client Secrets (Consultants)​

# Switch between clients
alias client-acme='eval "$(envcat get --bundle client-acme)"'
alias client-globex='eval "$(envcat get --bundle client-globex)"'

# Usage
client-acme
npm run dev  # Uses ACME secrets

client-globex
npm run dev  # Uses Globex secrets

Security Considerations​

Ephemeral Keypairs​

Each request generates a new keypair:

  • Private key: Stored in memory only, never written to disk
  • Public key: Sent to server for encryption
  • Keypair: Destroyed after use

End-to-End Encryption​

Server encrypts to CLI's public key (sealed box):

  • Only the CLI can decrypt
  • Server never sees plaintext in this flow

.env File Permissions​

Files written with --write have 0600 permissions (read/write owner only).

Verify:

envcat get --write .env
ls -l .env
# -rw------- 1 user user 123 Oct 18 10:00 .env

Git Safety​

Warning: The CLI warns if writing .env inside a git repository.

Best practice: Add .env to .gitignore:

echo ".env" >> .gitignore

Process Environment Visibility​

Environment variables are visible to:

  • Child processes
  • /proc/<pid>/environ (Linux)
  • Crash dumps, core dumps

Recommendation: Use ephemeral shells or load secrets on-demand.

Troubleshooting​

CLI Not Found​

Error: bash: constants: command not found

Solution:

# Check PATH
echo $PATH

# Add to PATH or use full path
export PATH="$PATH:/path/to/cli"
# Or
/path/to/cli/envcat get

Connection Refused​

Error: Error: connection refused

Solution: Check your network connection and verify env.cat is accessible:

curl https://env.cat/healthz

For self-hosted instances, check that your instance is running.

Request Expired​

Error: Error: request expired or not found (404)

Solution: Requests expire after 5 minutes. Create a new request:

envcat get --bundle dev/example

QR Code Issues​

Issue: QR code garbled or unreadable.

Solution: Use the URL shown below the QR code. The ASCII QR requires color terminal support.

Variables Not in Shell​

Issue: Ran CLI but variables not available.

Solution: Must use eval:

# Wrong
envcat get

# Right
eval "$(envcat get)"

Development​

Building from Source​

cd cli
go build -o envcat ./cmd/constants

Running Tests​

cd cli
go test ./...

Cross-Compilation​

# Linux
GOOS=linux GOARCH=amd64 go build -o constants-linux-amd64

# macOS
GOOS=darwin GOARCH=amd64 go build -o constants-darwin-amd64

# Windows (future)
GOOS=windows GOARCH=amd64 go build -o constants-windows-amd64.exe

Future Commands​

Planned for M8-M12:

  • constants login - Authenticate (M9)
  • constants logout - Logout (M9)
  • constants bundles list - List bundles (M10)
  • constants bundles create - Create bundle (M10)
  • constants bundles import - Import .env (M10)
  • constants scan - Scan for leaked secrets (M12)

Detailed command documentation coming in M1-M3 implementation.

For now, refer to: