CLI Go cv

A partir da v1.8.1, o CipherVault tem CLI oficial em Go — single binary cobrindo administração + consumo via terminal.

Instalação

Linux / macOS

# Homebrew (em breve)
brew install ciphervault/tap/cv

# Manual — baixar do GitHub Releases
curl -LO https://github.com/Martinez1991/ciphervault/releases/latest/download/cv-linux-amd64.tar.gz
tar -xzf cv-linux-amd64.tar.gz
sudo mv cv /usr/local/bin/

Windows

# Scoop (em breve)
scoop install cv

# Manual
Invoke-WebRequest -Uri "https://github.com/Martinez1991/ciphervault/releases/latest/download/cv-windows-amd64.zip" -OutFile cv.zip
Expand-Archive cv.zip

Configuração

Três opções (precedência: flags > env > config file):

1. Flags

cv secret list --url https://cv.acme.com.br --token <JWT>

2. Variáveis de ambiente

export CV_URL=https://cv.acme.com.br
export CV_TOKEN=<JWT>
cv secret list

3. Config file

cv login   # interativo

Salva em ~/.ciphervault/config.yaml (mode 0600):

url: https://cv.acme.com.br
token: <JWT>
output: table   # default; também: json | raw

Grupos de comandos

Grupo	Subcomandos
login	autenticar e salvar config
secret	list, get, set, delete
lease	request, release, list (Dynamic Secrets)
ssh	sign, roles, revoke (SSH CA)
eaas	encrypt, decrypt, keys list/rotate
pki	issue, roles, revoke
approval	list, approve, reject

Use cv <grupo> --help para detalhes de cada subcomando.

Exemplos

Secret CRUD

cv secret list --vault producao
cv secret get producao/api/stripe/secret_key
cv secret set producao/api/openai/key --value "sk-..." --reason "Rotação trimestral"
cv secret delete producao/api/old/key --reason "Migrado para v2"

Dynamic Secret lease

LEASE=$(cv lease request 42 --ttl 600 --output json)
USER=$(echo "$LEASE" | jq -r .username)
PASS=$(echo "$LEASE" | jq -r .password)

PGPASSWORD="$PASS" psql -h db.acme.com.br -U "$USER" -d billing

SSH cert

cv ssh sign ~/.ssh/id_ed25519.pub \
  --role-id 1 \
  --reason "Deploy hotfix" \
  > ~/.ssh/id_ed25519-cert.pub

ssh -i ~/.ssh/id_ed25519 deploy@bastion.acme.com.br

Encryption-as-a-Service (pipe-friendly)

echo "Rafael Martinez" | cv eaas encrypt pii --output raw
# eaas:v1:pii:3:dGVzdA==:cGxhaW50ZXh0Y2lwaGVy:dGFn

# Round-trip via pipe
echo "Rafael" | cv eaas encrypt pii --output raw | cv eaas decrypt pii --output raw
# Rafael

PKI

cv pki issue \
  --role 1 \
  --cn billing-api.svc.acme.internal \
  --san billing-api.svc.acme.internal \
  --ttl 86400 \
  --reason "Deploy billing-api v1.4.0" \
  --out ./certs/

ls ./certs/
# cert.pem  key.pem  ca-chain.pem

Approvals

cv approval list                              # pendentes do tenant
cv approval list --all                         # incluindo histórico
cv approval approve req_01HXY... -r "OK"
cv approval reject req_01HXY... -r "Negado fora de janela"

Output formats

cv secret list                  # default: table (humano)
cv secret list --output json    # JSON estruturado (jq-friendly)
cv secret list --output raw     # apenas valor, pipe-friendly

raw ignora cabeçalhos e formatação — perfeito para pipes:

cv secret get producao/api/stripe/secret_key --output raw | curl -H "Authorization: Bearer $(cat -)" ...

Pipeline-friendly

Exit codes:

• 0 — sucesso
• 1 — erro genérico
• 2 — autenticação inválida
• 3 — recurso não encontrado
• 4 — operação requer aprovação (Approvals pendente)

Exemplo CI:

#!/bin/bash
set -euo pipefail

# Autentica via OIDC Federation (CI runner)
eval $(cv login --oidc-federation --conn app_01HXY...)

# Busca secret
DB_PASS=$(cv secret get producao/db/postgres/billing-master --output raw)

# Solicita lease se preferir
LEASE_JSON=$(cv lease request 42 --ttl 300 --output json)
DB_USER=$(echo "$LEASE_JSON" | jq -r .username)
DB_PASS=$(echo "$LEASE_JSON" | jq -r .password)

# Deploy
PGPASSWORD="$DB_PASS" psql -h db.acme.com.br -U "$DB_USER" -d billing < migration.sql

Boas práticas

• ~/.ciphervault/config.yaml mode 0600 — CLI valida e recusa se permissão for mais aberta
• Use --reason em todas operações destrutivas — mesmo opcional em alguns comandos, audit log fica mais útil
• Output raw apenas em pipes — para humano, table ou json
• cv login --oidc-federation em CI/CD — sem PAT estático no runner
• Verifique exit code 4 — significa que sua action está em fila de Approvals (não é erro fatal)