cli-anything-tigris

O que cli-anything-tigris faz?

Uma interface de linha de comando sem estado para armazenamento de objetos Tigris. Encapsula a CLI oficial tigris para que todos os primitivos do Tigris (snapshots, IAM, credenciais com escopo, OAuth) sejam acessíveis através de um único ponto de entrada amigável para agentes, com --json em todos os lugares.

Escopo

Este harness é exclusivo para a CLI oficial do Tigris. Ele executa o binário tigris e assume a autenticação do Tigris através de tigris login ou chaves de acesso do Tigris. Não é uma ferramenta de endpoint S3 genérica e não gerencia MinIO, Cloudflare R2, AWS S3 ou endpoints compatíveis com S3 arbitrários.

Instalação

# 1. Instalar a CLI subjacente do Tigris
npm install -g @tigrisdata/cli
# ou:
brew install tigrisdata/tap/tigris

# 2. Autenticar (OAuth via navegador)
tigris login

# 3. Instalar este harness
pip install cli-anything-tigris

Pré-requisitos:

• Python 3.10+
• CLI tigris no PATH (o alias do binário é t3)

Uso

Comandos Básicos

# Exibir ajuda
cli-anything-tigris --help

# Iniciar REPL interativo
cli-anything-tigris

# Whoami (saída JSON para agentes)
cli-anything-tigris --json auth whoami

# Listar buckets
cli-anything-tigris --json bucket list

# Fazer upload de um arquivo local
cli-anything-tigris --json object put --bucket meu-bucket --key caminho/para/arquivo.txt --file ./local.txt

# Baixar um objeto
cli-anything-tigris --json object get --bucket meu-bucket --key caminho/para/arquivo.txt --output ./out.txt

# Cópia no lado do servidor
cli-anything-tigris --json object cp t3://meu-bucket/src.txt t3://meu-bucket/dst.txt

# Tirar um snapshot
cli-anything-tigris --json snapshot take meu-bucket --name baseline-v1

# Excluir um bucket; `--yes` é obrigatório
cli-anything-tigris --json bucket delete --name bucket-antigo --yes

# Criar uma chave de acesso com escopo para uma execução de agente
cli-anything-tigris --json access-key create minha-chave-agente
cli-anything-tigris --json access-key assign tid_AaBb --bucket meu-bucket --role Editor

# Rotacionar ou excluir chaves de acesso; `--yes` é obrigatório
cli-anything-tigris --json access-key rotate tid_AaBb --yes
cli-anything-tigris --json access-key delete tid_AaBb --yes

# URL de download pré-assinada (1 hora)
cli-anything-tigris --json presign get --bucket meu-bucket --key caminho/para/arquivo.txt --expires 3600

Modo REPL

Quando invocada sem um subcomando, a CLI entra em um REPL interativo com autocompletar e histórico.

Grupos de Comandos

auth

Autenticação baseada em OAuth.

Comando	Descrição
login	Login OAuth via navegador (tigris login)
logout	Sair da sessão atual
whoami	Exibir usuário/organização autenticado

bucket

CRUD de buckets.

Comando	Descrição
list	Listar todos os buckets
create --name NOME	Criar um bucket
delete --name NOME --yes	Excluir um bucket vazio (--yes obrigatório)
info NOME	Obter informações do bucket

object

Operações de objetos (encapsula tigris ls/cp/rm/stat).

Comando	Descrição
list --bucket B [--prefix P] [--limit N]	Listar objetos
put --bucket B --key K (--file F | --text T)	Fazer upload de um objeto
get --bucket B --key K --output F	Baixar um objeto
delete --bucket B --key K	Excluir um objeto
info --bucket B --key K	Metadados do objeto (HEAD / stat)
cp SRC DST [-r]	Copiar. Aceita URIs t3:// ou tigris://.

presign

URLs com tempo limitado.

Comando	Descrição
get --bucket B --key K [--expires SEC]	URL de download pré-assinada
put --bucket B --key K [--expires SEC]	URL de upload pré-assinada

snapshot

Snapshots pontuais de buckets — um primitivo específico do Tigris.

Comando	Descrição
list BUCKET	Listar snapshots de um bucket
take BUCKET [--name N]	Tirar um snapshot

access-key

Credenciais programáticas com escopo — combine com snapshot para isolamento por agente.

Comando	Descrição
list	Listar todas as chaves de acesso
create NOME	Criar uma nova chave de acesso (segredo mostrado UMA VEZ)
get KEY_ID	Exibir detalhes da chave
delete KEY_ID --yes	Excluir permanentemente uma chave (--yes obrigatório)
assign KEY_ID --bucket B --role R	Escopar uma chave a um bucket + função
rotate KEY_ID --yes	Rotacionar o segredo de uma chave (--yes obrigatório)

iam

Políticas e usuários da organização.

Comando	Descrição
policy list	Listar políticas IAM
policy create NOME --document ARQUIVO	Criar uma política a partir de um arquivo JSON
user list	Listar usuários da organização
user invite EMAIL [--role R]	Convidar um usuário

Formatos de Saída

Todos os comandos suportam modos de saída duplos:

• Legível por humanos (padrão): tabelas, cores, texto formatado
• Legível por máquina (--json): envelope JSON (ou saída --format json da CLI upstream, ecoada literalmente)

Para Agentes de IA

Ao usar esta CLI programaticamente:

1. Sempre passe --json para saída analisável.
2. Verifique os códigos de retorno — 0 para sucesso, diferente de zero para erros.
3. Leia stderr para mensagens de erro.
4. object cp aceita URIs t3://bucket/key ou tigris://bucket/key; cópias no lado do servidor (t3 → t3) evitam completamente o round trip.
5. presign retorna uma URL em stdout no modo humano; no modo JSON é o campo url.
6. Para trabalho destrutivo: exclusão de bucket, exclusão de chave de acesso e rotação de chave de acesso exigem --yes explícito; tire um snapshot do bucket de destino primeiro, execute o trabalho e, em seguida, mantenha o snapshot ou descarte-o.
7. Para isolamento por agente: access-key create + access-key assign --bucket B --role Editor para criar uma chave com escopo em um bucket; revogue com access-key delete quando a execução do agente terminar.

Por que Tigris

• Distribuído globalmente. Dados colocados próximos de onde são lidos.
• Sem taxas de saída. Agentes puxando artefatos de qualquer lugar não incorrem em custos de largura de banda por região.
• Snapshots + credenciais com escopo. Primitivos que provedores genéricos compatíveis com S3 não oferecem — a base para isolamento por agente.
• Compatível com S3. Útil junto a ferramentas S3, mas este harness em si não é um gerenciador de endpoint S3/MinIO/R2/AWS genérico.

Versão

1.0.0