herdux-cli 0.5.0 → 0.8.2

package/README.pt-BR.md

@@ -8,11 +8,11 @@
   <img src=".github/assets/logo.svg" alt="Herdux banner" style="max-width: 100%; width: 600px;" />
 </p>
 
-## ⏭️ Herdux — Database Workflow CLI
+## Herdux — Database Workflow CLI
 
 Uma CLI rápida e interativa que remove a fricção dos workflows diários com bancos de dados locais, especialmente ao lidar com múltiplas instâncias e grandes datasets.
 
-![Version](https://img.shields.io/badge/version-0.5.0-blue.svg)
+![Version](https://img.shields.io/badge/version-0.8.2-blue.svg)
 ![License](https://img.shields.io/badge/license-MIT-green.svg)
 ![Node](https://img.shields.io/badge/node-18%2B-43853d.svg)
 ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-316192?style=flat&logo=postgresql&logoColor=white)
@@ -23,27 +23,21 @@ Uma CLI rápida e interativa que remove a fricção dos workflows diários com b
 
 > Otimizado para ambientes locais e de desenvolvimento. O uso em produção é suportado com configuração explícita.
 
-<!-- <p align="center">
-  <img src=".github/herdux.gif" alt="herdux terminal gif" width="1220" />
-</p> -->
-
 ---
 
-## ⚡ Início Rápido
+## Início Rápido
 
 ```bash
 npm install -g herdux-cli
 
-# Você pode usar 'herdux' ou o alias mais curto 'hdx'
+# Use 'herdux' ou o alias mais curto 'hdx'
 hdx doctor
 herdux list
 ```
 
-É só isso. Você já está gerenciando bancos de dados.
-
 ---
 
-## 🔌 Engines Suportadas
+## Engines Suportadas
 
 | Engine     | Status | Ferramentas Cliente Necessárias |
 | ---------- | ------ | ------------------------------- |
@@ -51,33 +45,22 @@ herdux list
 | MySQL      | ✅     | `mysql`, `mysqldump`            |
 | SQLite     | ✅     | `sqlite3`                       |
 
-O Herdux detecta automaticamente a engine a partir do seu perfil de servidor ou da flag `--engine`. PostgreSQL é o padrão quando nenhuma engine é especificada.
+Use `--engine <nome>` ou configure a engine em um perfil salvo. PostgreSQL é o padrão.
 
 ```bash
-# PostgreSQL (padrão)
-herdux list
-herdux create mydb
-
-# MySQL
-herdux --engine mysql list
-herdux --engine mysql create mydb
-
-# SQLite (baseado em arquivos, sem servidor)
-herdux --engine sqlite list
-herdux --engine sqlite create mydb
-
-# Ou salve no perfil e esqueça
-herdux config add mysql-local --port 3306 --user root --password secret --engine mysql
-herdux list -s mysql-local
+herdux list                        # PostgreSQL (padrão)
+herdux --engine mysql list         # MySQL
+herdux --engine sqlite list        # SQLite (baseado em arquivos, sem servidor)
+herdux list -s meu-perfil          # Usando um perfil de servidor salvo
 ```
 
 ---
 
 ## Por que Herdux?
 
-Gerenciar bancos de dados locais através de scripts bash ou binários crus é repetitivo, propenso a erros e doloroso em escala.
+Gerenciar bancos de dados locais por meio de binários brutos é repetitivo, propenso a erros e diferente para cada engine.
 
-### ❌ Sem Herdux
+**Antes:**
 
 ```bash
 # Backup PostgreSQL
@@ -86,15 +69,14 @@ pg_dump -U postgres -h localhost -p 5416 -Fc -f ./backups/mydb.dump mydb
 # Backup MySQL
 mysqldump -u root -h localhost -P 3306 -p mydb > ./backups/mydb.sql
 
-# Dropar manualmente, restaurar, verificar ferramentas...
 # Flags diferentes, ferramentas diferentes, memória muscular diferente para cada engine.
 ```
 
-### ✅ Com Herdux
+**Depois:**
 
 ```bash
 herdux backup mydb --drop --yes        # Backup + drop em um comando
-herdux restore ./backups/mydb.dump --db mydb   # Cria o banco (se faltar) e detecta o formato
+herdux restore ./backups/mydb.dump --db mydb   # Detecta formato, cria DB se necessário
 herdux clean                            # Multi-seleção e batch-drop de bancos
 herdux doctor                           # Verificação completa do sistema
 ```
@@ -103,80 +85,23 @@ Mesmos comandos. Qualquer engine. Menos flags. Menos erros. Zero fadiga de termi
 
 ---
 
-## 🎯 Para quem é o Herdux?
-
-O **Herdux** foi construído _por desenvolvedores, para desenvolvedores_.
-
-Ele nasceu da frustração diária de ter que constantemente restaurar backups para testar um estado específico, dropar bancos corrompidos durante o desenvolvimento e lidar com binários crus de bancos de dados toda hora.
-
-Ele é especificamente projetado para desenvolvedores que:
-
-- Gerenciam infraestruturas locais e precisam verificar o tamanho dos discos antes de popular novos bancos.
-- Querem clonar, popular (seed) e resetar bancos de dados rapidamente sem precisar ler documentações complexas.
-- Precisam de fluxos seguros de backup & restore que não dependam de scripts bash frágeis.
-- Preferem ferramentas focadas no terminal (terminal-first).
-- Querem resolução previsível de conexões sem mágicas ocultas.
-- Trabalham com **múltiplas engines de banco de dados** (PostgreSQL, MySQL, SQLite) e querem uma interface unificada.
-
-Se você gerencia bancos de dados localmente e compartilha dessa dor, o Herdux foi criado para você.
-
----
-
-## 🚀 Funcionalidades Principais
-
-- **🔌 Suporte Multi-Engine** — Suporte de primeira classe para PostgreSQL, MySQL e SQLite. Mesmos comandos, mesmo workflow, qualquer engine.
-- **📋 Listagem Inteligente** — Estratégia otimizada para clusters massivos. Flag opcional `--size` para análise de uso de disco, ordenado do maior para o menor.
-- **💾 Backup & Restore Inteligente** — Suporta formatos Custom (`.dump`) e Plain (`.sql`). Detecta automaticamente a ferramenta correta para restauração.
-- **🧹 Limpeza em Massa** — Multi-seleção de bancos, backup opcional e batch-drop. Recupere espaço em disco instantaneamente.
-- **🩺 Diagnóstico do Sistema** — Verificação completa de saúde com um único comando: binários, autenticação e conectividade.
-- **⚙️ Perfis Persistentes** — Salve configurações de servidor nomeadas com tipo de engine. Alterne entre ambientes com `-s pg16`.
-- **🎯 Resolução Inteligente de Conexão e Engine** — Flags CLI explícitas → perfis → padrões salvos → auto-descoberta. Sempre previsível.
-
----
-
-## 💡 Filosofia
-
-**Herdux** combina _herd_ (manada/rebanho) e _UX_ — entregando uma melhor Developer Experience ao gerenciar seus clusters de bancos de dados. O nome reflete nosso foco em melhorar a experiência de desenvolvimento ao gerenciar "manadas" de bancos.
-
-O **Herdux** segue três princípios:
-
-- **Segurança primeiro** — Nunca apaga dados sem confirmação explícita ou um backup verificado.
-- **Explícito sobre implícito** — A resolução de conexão e engine segue uma prioridade estrita e documentada. Sem mágica.
-- **Otimização de workflow** — Cada comando é projetado para te salvar de tarefas repetitivas no terminal.
-
----
-
-## 🔒 Segurança
-
-O **Herdux** trata operações destrutivas com cuidado:
-
-- **Nunca dropa um banco** sem confirmação explícita
-- **Aborta toda a operação** se um backup de segurança falhar durante o `herdux clean`
-- **Valida códigos de saída das ferramentas de backup** antes de considerar um backup bem-sucedido
-- **Requer a flag `--drop`** intencionalmente — dropar nunca é o padrão
-- **`--yes` deve ser combinado com `--drop`** — não é possível pular confirmação sozinho
-
-> Se você solicitar um backup antes de dropar e esse backup falhar, o **Herdux** para imediatamente. Nenhum dado é perdido.
-
----
-
-## 🧩 Requisitos
+## Requisitos
 
 - **Node.js** 18 ou superior
-- **Para PostgreSQL:** `psql`, `pg_dump`, `pg_restore` instalados e disponíveis no `PATH`
-- **Para MySQL:** `mysql`, `mysqldump` instalados e disponíveis no `PATH`
-- **Para SQLite:** `sqlite3` instalado e disponível no `PATH`
+- **Para PostgreSQL:** `psql`, `pg_dump`, `pg_restore` instalados e no `PATH`
+- **Para MySQL:** `mysql`, `mysqldump` instalados e no `PATH`
+- **Para SQLite:** `sqlite3` instalado e no `PATH`
 
 > [!TIP]
-> Execute `herdux doctor` após a instalação para verificar se tudo está configurado corretamente. O comando doctor verifica as ferramentas da engine ativa.
+> Execute `herdux doctor` após a instalação para verificar se tudo está configurado corretamente.
 
 ---
 
-## 📦 Instalação
+## Instalação
 
 **npm (recomendado):**
 
-> **⚠️ IMPORTANTE:** Você precisa usar a flag `-g` (global) para que a CLI fique disponível no seu terminal.
+> **Importante:** Use a flag `-g` para que a CLI fique disponível em qualquer lugar no terminal.
 
 ```bash
 npm install -g herdux-cli
@@ -194,9 +119,7 @@ npm link
 
 ---
 
-## 🛠️ Comandos
-
-Todos os comandos funcionam com PostgreSQL, MySQL e SQLite. Use `--engine mysql` ou `--engine sqlite`, ou configure a engine no seu perfil de servidor.
+## Comandos
 
 ### `herdux version`
 
@@ -209,11 +132,7 @@ herdux --engine mysql version
 
 ### `herdux doctor`
 
-Executa uma verificação completa de saúde do sistema:
-
-- Verifica se as ferramentas cliente necessárias estão instaladas e acessíveis (específicas por engine)
-- Tenta uma conexão real usando a configuração resolvida
-- Testa autenticação contra o servidor alvo
+Executa uma verificação completa do sistema: verifica ferramentas cliente, testa conectividade e valida autenticação.
 
 ```bash
 herdux doctor
@@ -222,17 +141,17 @@ herdux --engine mysql doctor
 
 ---
 
-### 📋 `herdux list`
+### `herdux list`
 
 Lista todos os bancos de dados no servidor conectado.
 
 ```bash
-herdux list              # Listagem rápida (nome, owner, encoding)
-herdux ls --size         # Inclui tamanho em disco, ordenado do maior → menor
+herdux list              # Nome, owner, encoding
+herdux ls --size         # Inclui tamanho em disco, ordenado do maior para o menor
 ```
 
 > [!NOTE]
-> A flag `--size` calcula o uso físico de disco. Em servidores com dezenas de bancos multi-GB, isso pode levar alguns minutos dependendo da velocidade do disco.
+> A flag `--size` calcula o uso físico de disco. Em servidores com dezenas de bancos de vários GBs, isso pode levar alguns minutos.
 
 ---
 
@@ -241,8 +160,8 @@ herdux ls --size         # Inclui tamanho em disco, ordenado do maior → menor
 Cria um novo banco de dados.
 
 ```bash
-herdux create meu_novo_db
-herdux --engine mysql create meu_novo_db
+herdux create meu_novo_banco
+herdux --engine mysql create meu_novo_banco
 ```
 
 ### `herdux drop <nome>`
@@ -250,209 +169,238 @@ herdux --engine mysql create meu_novo_db
 Remove um banco de dados com confirmação interativa.
 
 ```bash
-herdux drop meu_banco_antigo
+herdux drop banco_antigo
 ```
 
 ---
 
-### 🧹 `herdux clean` — Limpeza em Massa
-
-Trabalhando com bancos de desenvolvimento cheios de seeds? Precisa recuperar espaço em disco rápido?
+### `herdux clean`
 
-`herdux clean` permite:
-
-- **Multi-seleção** de bancos a partir de uma interface interativa com checkboxes
-- **Gerar backups de segurança opcionais** antes de qualquer ação destrutiva
-- **Batch-drop** de todos os bancos selecionados com segurança
-- **Abortar imediatamente** se qualquer backup falhar, prevenindo perda de dados
+Limpeza em massa interativa: selecione vários bancos, gere backups de segurança e remova-os em lote.
 
 ```bash
 herdux clean
 ```
 
-Projetado para o workflow real do desenvolvedor: clonar bancos, experimentar, depois limpar tudo de uma vez.
+Aborta imediatamente se algum backup de segurança falhar. Nenhum dado é removido sem um backup confirmado.
 
 ---
 
-### 📦 `herdux backup <banco>`
+### `herdux backup <database>`
 
-Gera um backup com timestamp em `./backups/`.
+Cria um backup com timestamp em `~/.herdux/backups/` por padrão.
 
 ```bash
-herdux backup mydb                       # Formato custom (.dump para PG, .sql para MySQL)
-herdux backup mydb --format plain        # SQL puro (.sql)
-herdux backup mydb --drop                # Backup, depois pergunta se quer dropar
-herdux backup mydb --drop --yes          # Backup + drop, sem perguntas
-herdux backup mydb -o ./meus-backups     # Diretório de saída personalizado
+herdux backup mydb                             # Formato nativo da engine (.dump para PG, .db para SQLite, .sql para MySQL)
+herdux backup mydb --format plain              # SQL puro (.sql)
+herdux backup mydb --drop                      # Backup e depois pergunta se quer dropar
+herdux backup mydb --drop --yes                # Backup + drop sem confirmacao
+herdux backup mydb -o ./meus-backups           # Diretorio de saida personalizado
+herdux backup mydb --upload backups/           # Backup e upload para o prefixo backups/ no S3
+herdux backup mydb --upload backups/ --no-keep # Backup, upload e deleta o arquivo local
 ```
 
-| Opção                 | Descrição                                                  |
-| --------------------- | ---------------------------------------------------------- |
-| `-F, --format <tipo>` | `custom` (padrão, comprimido) ou `plain` (SQL puro)        |
-| `-d, --drop`          | Pergunta se deseja dropar o banco após backup bem-sucedido |
-| `-y, --yes`           | Pula confirmação do drop (requer `--drop`)                 |
-| `-o, --output <dir>`  | Diretório de saída (padrão: `./backups`)                   |
+| Opcao                 | Descricao                                                           |
+| --------------------- | ------------------------------------------------------------------- |
+| `-F, --format <tipo>` | `custom` (padrao, nativo da engine) ou `plain` (SQL)                |
+| `-d, --drop`          | Pergunta se quer dropar o banco apos o backup bem-sucedido          |
+| `-y, --yes`           | Pula a confirmacao de drop (requer `--drop`)                        |
+| `-o, --output <dir>`  | Diretorio de saida (padrao: `~/.herdux/backups`)                    |
+| `--upload [prefix]`   | Faz upload do backup para o S3 apos a criacao (requer cloud config) |
+| `--no-keep`           | Deleta o arquivo local apos upload bem-sucedido (requer `--upload`) |
 
 ---
 
-### 📥 `herdux restore <arquivo>`
-
-Restaura um banco de dados a partir de um arquivo de backup. Detecta automaticamente o formato:
+### `herdux restore <arquivo>`
 
-- `.sql` → usa a ferramenta de importação SQL apropriada
-- `.dump` ou qualquer outra extensão → usa a ferramenta de restore apropriada
+Restaura um banco de dados a partir de um arquivo de backup. Detecta automaticamente o formato pela extensão.
 
 ```bash
 herdux restore ./backups/mydb_2026-02-23.dump --db mydb
 herdux restore ./exports/data.sql --db mydb
+herdux restore archive.bkp --db mydb --format custom   # Forçar formato
 ```
 
-Precisa sobrescrever a auto-detecção? Use `--format`:
-
-```bash
-herdux restore arquivo.bkp --db mydb --format custom
-herdux restore script.txt --db mydb --format plain
-```
+O banco de dados é criado automaticamente se não existir.
 
 > [!NOTE]
-> Ao restaurar backups vindos de ambientes gerenciados (ex: AWS RDS), o Herdux configura automaticamente a engine subjacente para ignorar atribuições de permissões e roles. Isso evita erros com roles que existem em produção mas não no seu ambiente local. Se a engine de restauração concluir a operação com avisos não-fatais (como roles ausentes), o Herdux irá te informar no terminal e prosseguir normalmente sem interromper o fluxo.
+> Ao restaurar dumps de ambientes gerenciados (ex: AWS RDS), o Herdux configura a ferramenta de restauração para ignorar ownership e ACLs, evitando erros por roles de produção ausentes localmente.
 
 ---
 
-## ⚙️ Configuração & Perfis de Servidor
+### `herdux inspect <arquivo>`
 
-O `herdux` armazena configurações localmente em `~/.herdux/config.json`.
+Inspeciona o conteúdo de um arquivo de backup sem se conectar ao banco de dados. Funciona completamente offline.
 
-### Definir Padrões Globais
+| Extensão          | Output                                                                         |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `.dump`           | Formato custom do PostgreSQL: Table of Contents completo (`pg_restore --list`) |
+| `.tar`            | Formato tar do PostgreSQL: Table of Contents completo (`pg_restore --list`)    |
+| `.sql`            | SQL puro (qualquer engine): declarações CREATE TABLE, VIEW, INDEX, SEQUENCE    |
+| `.db` / `.sqlite` | Arquivo SQLite: schema (`sqlite3 .schema`)                                     |
 
 ```bash
-herdux config set engine postgres        # Engine padrão
-herdux config set user postgres
-herdux config set password minha_senha
-herdux config set port 5432
+hdx inspect backup.dump           # Table of Contents de um dump custom do PostgreSQL
+hdx inspect backup.tar            # Table of Contents de um dump tar do PostgreSQL
+hdx inspect export.sql            # CREATE statements extraídos de SQL puro
+hdx inspect mydb.db               # Schema do SQLite
 ```
 
-### Perfis de Servidor Nomeados
+---
 
-Gerencie múltiplas instâncias de banco de dados sem esforço:
+### `herdux docker`
+
+Gerencia containers de banco de dados rodando via Docker. Nao requer conexao ativa com o banco.
 
 ```bash
-# Perfis PostgreSQL
-herdux config add pg16 --port 5416
-herdux config add pg17 --port 5417 --user admin
+hdx docker list             # Lista containers postgres/mysql em execucao
+hdx docker list --all       # Inclui containers parados
+hdx docker start pg-dev     # Inicia um container parado
+hdx docker stop pg-dev      # Para um container em execucao
+hdx docker stop pg-dev --remove   # Para e remove o container
+```
 
-# Perfis MySQL (a engine é salva no perfil)
-herdux config add mysql-dev --port 3306 --user root --password secret --engine mysql
+---
 
-# Servidores remotos
-herdux config add staging --host 192.168.0.10 --port 5432
-```
+### `herdux cloud`
 
-Depois conecte usando a flag `-s`:
+Gerencia arquivos de backup em cloud storage S3-compatible (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces e outros).
 
 ```bash
-herdux list -s pg16
-herdux backup mydb -s mysql-dev
+# Configurar
+hdx cloud config bucket meu-bucket
+hdx cloud config region us-east-1
+hdx cloud config access-key AKIAIO...
+hdx cloud config secret-key wJalrX...
+hdx cloud config endpoint https://account.r2.cloudflarestorage.com  # opcional, para provedores nao-AWS
+
+# Navegar e gerenciar backups no bucket
+hdx cloud list                                    # Modo diretorio: lista filhos imediatos na raiz
+hdx cloud list backups/mydb/                      # Lista filhos imediatos no caminho (posicional)
+hdx cloud list --prefix backups/mydb/             # Mesmo que acima (forma de flag)
+hdx cloud list --recursive                        # Lista todos os objetos no bucket
+hdx cloud list backups/ --recursive               # Lista todos os objetos sob um prefixo
+hdx cloud download backups/mydb_2026-03-03.dump              # Salva em ~/.herdux/backups/
+hdx cloud download backups/mydb_2026-03-03.dump -o /tmp/     # Salva em diretorio personalizado
+hdx cloud upload ./mydb_2026-03-03.dump                      # Envia arquivo local para a raiz do bucket
+hdx cloud upload ./mydb_2026-03-03.dump --prefix backups/    # Envia sob um prefixo
+hdx cloud delete backups/mydb_2026-03-03.dump     # Verifica existencia e pede confirmacao
+hdx cloud delete backups/mydb_2026-03-03.dump --yes
+
+# Backup direto para o S3
+hdx backup mydb --upload backups/              # Backup e upload para o prefixo backups/
+hdx backup mydb --upload                       # Backup e upload para a raiz do bucket
+hdx backup mydb --upload backups/ --no-keep    # Backup, upload e deleta o arquivo local
+
+# Restore direto do S3
+hdx restore s3://meu-bucket/backups/mydb_2026-03-03.dump --db mydb
 ```
 
-Ou simplesmente execute um comando sem flags — se você tiver perfis salvos, o Herdux mostrará um menu de seleção interativo exibindo a engine de cada perfil.
-
-### Visualizar & Gerenciar Config
+As credenciais tambem podem ser fornecidas via variaveis de ambiente (recomendado para CI/producao):
 
 ```bash
-herdux config list           # Mostra todas as configurações e perfis salvos
-herdux config get port       # Obtém um valor específico
-herdux config rm pg16        # Remove um perfil de servidor
-herdux config reset          # Limpa toda a configuração
+export AWS_ACCESS_KEY_ID=AKIAIO...
+export AWS_SECRET_ACCESS_KEY=wJalrX...
+export AWS_DEFAULT_REGION=us-east-1
 ```
 
 ---
 
-## 🔌 Resolução de Conexão e Engine
-
-Ao resolver como se conectar e qual engine usar, o **Herdux** segue uma ordem de prioridade estrita e previsível:
+## Configuração e Perfis de Servidor
 
-### Prioridade da Engine
+A configuração é armazenada em `~/.herdux/config.json`.
 
-| Prioridade | Fonte            | Exemplo                          |
-| ---------- | ---------------- | -------------------------------- |
-| 1️⃣         | **Flag CLI**     | `herdux --engine mysql list`     |
-| 2️⃣         | **Perfil**       | Campo `engine` do perfil         |
-| 3️⃣         | **Padrão salvo** | `herdux config set engine mysql` |
-| 4️⃣         | **Fallback**     | `postgres`                       |
+### Valores globais padrão
 
-### Prioridade da Conexão
+```bash
+herdux config set engine postgres
+herdux config set user postgres
+herdux config set password minha_senha
+herdux config set port 5432
+```
 
-| Prioridade | Fonte                  | Exemplo                                                 |
-| ---------- | ---------------------- | ------------------------------------------------------- |
-| 1️⃣         | **Flags CLI**          | `herdux list --port 5417`                               |
-| 2️⃣         | **Perfil de servidor** | `herdux list -s pg16`                                   |
-| 3️⃣         | **Padrões salvos**     | `herdux config set port 5432`                           |
-| 4️⃣         | **Auto-descoberta**    | Escaneia portas comuns; pergunta se encontrar múltiplas |
+### Perfis de servidor nomeados
 
-Isso significa que a entrada explícita sempre vence. Sem surpresas.
+```bash
+herdux config add pg16 --port 5416
+herdux config add pg17 --port 5417 --user admin
+herdux config add mysql-dev --port 3306 --user root --password secret --engine mysql
+herdux config add staging --host 192.168.0.10 --port 5432
+```
 
----
+Use perfis com a flag `-s`:
 
-## 🤔 Por que não pgAdmin / phpMyAdmin?
+```bash
+herdux list -s pg16
+herdux backup mydb -s mysql-dev
+```
 
-O **Herdux** não é um substituto de GUI.
-É um acelerador de workflow para desenvolvedores que vivem no terminal.
+### Gerenciar configuração
 
-Sem GUI. Sem overhead. Só velocidade.
+```bash
+herdux config list           # Mostrar todas as configurações e perfis
+herdux config get port       # Obter um valor específico
+herdux config rm pg16        # Remover um perfil
+herdux config reset          # Limpar toda a configuração
+```
 
 ---
 
-## 🧠 Princípios de Design
+## Resolução de Conexão e Engine
 
-- Sem padrões ocultos (hidden defaults).
-- Sem mágicas destrutivas.
-- Resolução determinística de conexão e engine.
-- Comandos explícitos e combináveis.
-- Engine-agnostic: mesma interface, qualquer banco de dados.
+O Herdux segue uma prioridade estrita e previsível ao resolver como se conectar.
 
----
+**Prioridade de engine:**
 
-## 🐳 Suporte Docker (Em Breve)
+| Prioridade | Fonte        | Exemplo                          |
+| ---------- | ------------ | -------------------------------- |
+| 1          | Flag CLI     | `herdux --engine mysql list`     |
+| 2          | Perfil       | Campo `engine` do perfil         |
+| 3          | Padrão salvo | `herdux config set engine mysql` |
+| 4          | Fallback     | `postgres`                       |
 
-O **Herdux** poderá detectar e interagir com instâncias de banco de dados rodando dentro de containers Docker — listando, conectando e gerenciando-as tão naturalmente quanto instâncias locais.
+**Prioridade de conexão:**
 
----
+| Prioridade | Fonte          | Exemplo                                    |
+| ---------- | -------------- | ------------------------------------------ |
+| 1          | Flags CLI      | `herdux list --port 5417`                  |
+| 2          | Perfil         | `herdux list -s pg16`                      |
+| 3          | Padrões salvos | `herdux config set port 5432`              |
+| 4          | Auto-discovery | Escaneia portas comuns; pergunta se vários |
 
-## 🗺 Roadmap
-
-Consulte o [ROADMAP.md](./ROADMAP.md) para ver nossos planos futuros detalhados, incluindo integração com Docker e backups criptografados.
+Input explícito sempre vence. Sem surpresas.
 
 ---
 
-## 🤝 Contribuindo
-
-PRs são bem-vindas! Por favor, abra uma issue primeiro para discutir mudanças significativas.
+## Contribuindo
 
 ```bash
 git clone https://github.com/herdux/herdux-cli.git
 cd herdux-cli
 npm install
-npm run dev
 
-# Executar testes unitários
-npm run test:unit
-# Executar testes E2E (requer Docker)
-npm run test:e2e:pgsql
-npm run test:e2e:mysql
+npm run test:unit           # Testes unitários (238 testes, todas as engines)
+npm run test:integration    # Testes de integração
+npm run test:e2e:pgsql      # Testes E2E para PostgreSQL (requer Docker)
+npm run test:e2e:mysql      # Testes E2E para MySQL (requer Docker)
+npm run test:e2e:sqlite     # Testes E2E para SQLite (requer sqlite3)
 ```
 
+O Herdux segue limites arquiteturais estritos: comandos são agnósticos de engine, engines encapsulam todo comportamento específico de banco, e todos os binários são isolados por adaptadores. Mantenha esses limites ao contribuir.
+
+PRs são bem-vindos. Abra uma issue primeiro para mudanças maiores.
+
 ---
 
-## ☕ Apoie o Projeto
+## Suporte
 
-Se o **Herdux** tem te salvado horas de dores de cabeça com bancos de dados, considere apoiar o projeto! Isso ajuda demais a mantê-lo ativo e open-source.
+Se o Herdux te salvou horas de debugging e trabalho com bancos de dados, considere apoiar o projeto:
 
 <a href="https://github.com/sponsors/eduardozaniboni" target="_blank"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?style=for-the-badge&logo=github" alt="GitHub Sponsors"></a>
 <a href="https://www.buymeacoffee.com/eduardozaniboni" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 28px !important;width: 100px !important;" ></a>
 
 ---
 
-## 📄 Licença
+## Licença
 
 MIT

package/dist/commands/backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+G5D"}
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8J5D"}

package/dist/commands/backup.js

@@ -3,8 +3,11 @@ import ora from "ora";
 import prompts from "prompts";
 import { resolveEngineAndConnection } from "../infra/engines/resolve-connection.js";
 import * as config from "../infra/config/config.service.js";
-import { join } from "path";
+import { resolveCloudCredentials } from "../infra/cloud/cloud-credential.js";
+import { uploadFile } from "../infra/cloud/s3.service.js";
+import { basename, join } from "path";
 import { homedir } from "os";
+import { unlinkSync } from "fs";
 export function registerBackupCommand(program) {
     program
         .command("backup <database>")
@@ -15,11 +18,16 @@ Examples:
   hdx backup mydb --output /tmp/backups
   hdx backup mydb --format plain
   hdx backup mydb --drop --yes     # Backup then drop without confirmation
-  hdx backup mydb --engine mysql`)
+  hdx backup mydb --engine mysql
+  hdx backup mydb --upload backups/
+  hdx backup mydb --upload          # Upload to bucket root
+  hdx backup mydb --upload --no-keep   # Upload and delete local file`)
         .option("-o, --output <dir>", "Output directory for the backup (overrides global config)")
         .option("-d, --drop", "Ask to drop the database after a successful backup")
         .option("-y, --yes", "Skip confirmation when dropping (requires --drop)")
         .option("-F, --format <type>", "Backup format format (custom, plain)", "custom")
+        .option("-u, --upload [prefix]", "Upload backup to configured S3 bucket after backup")
+        .option("--no-keep", "Delete local backup after successful upload (requires --upload)")
         .action(async (database, cmdOpts) => {
         if (/[\s;|&`$<>(){}\\]/.test(database)) {
             console.error(chalk.red(`\n✖ Invalid database name "${database}". Avoid spaces and special characters (; | & \` $ < > ( ) { } \\).\n`));
@@ -43,6 +51,25 @@ Examples:
             const spinner = ora(`Generating backup for "${database}"...`).start();
             const outputPath = await engine.backupDatabase(database, finalOutputDir, opts, cmdOpts.format);
             spinner.succeed(`Backup saved at ${chalk.cyan(outputPath)}\n`);
+            if (cmdOpts.upload !== undefined) {
+                const cloud = config.getCloudConfig();
+                if (!cloud.bucket) {
+                    console.error(chalk.red("✖ Bucket not configured. Run: hdx cloud config bucket NAME\n"));
+                    process.exit(1);
+                }
+                const creds = resolveCloudCredentials(cloud);
+                const prefix = typeof cmdOpts.upload === "string" ? cmdOpts.upload : "";
+                const key = prefix
+                    ? `${prefix.replace(/\/$/, "")}/${basename(outputPath)}`
+                    : basename(outputPath);
+                const uploadSpinner = ora(`Uploading to s3://${cloud.bucket}/${key}...`).start();
+                const s3Url = await uploadFile(outputPath, cloud.bucket, key, creds);
+                uploadSpinner.succeed(`Uploaded: ${chalk.cyan(s3Url)}\n`);
+                if (!cmdOpts.keep) {
+                    unlinkSync(outputPath);
+                    console.log(chalk.gray(`  Local backup deleted.\n`));
+                }
+            }
             if (cmdOpts.drop) {
                 let shouldDrop = cmdOpts.yes;
                 if (!shouldDrop) {