# backupally quick

Executa backups rápidos sem necessidade de configuração prévia.

# Sintaxe

backupally quick <ORIGEM> -d <DESTINO> [OPÇÕES]

# Argumentos

# Opções Obrigatórias

# Opções de Storage

s3/b2 não estão implementados no quick (desde 0.34.1). O quick só grava de fato em local — -t s3/-t b2 recusam antes de tocar a origem, com error.code: E9002 (NotImplemented) e exit ≠ 0. Antes da 0.34.1 o comando fingia sucesso: dormia, dizia "concluído" e não subia nada — corrigido porque sucesso vazio é o pior resultado possível para backup. Para nuvem, use uma task com [[storage]] s3/b2, ou baixe manualmente para local e suba por fora. backupally --capabilities lista o que o quick grava de verdade em data.quick.storage_types (hoje ["local"]", separado de storage_drivers, que são os drivers de storage/ usados por tasks).

# `--credentials-ref` (desde 0.34.0)

Resolve a credencial do cofre local (secret set) em vez de recebê-la por --access-key/--secret-key em texto puro:

backupally secret set minha-nuvem_access_key --stdin <<< "AKIA..."
backupally secret set minha-nuvem_secret_key --stdin <<< "wJal..."

backupally quick /data -d /backups/ -z --credentials-ref minha-nuvem

A convenção é <nome>_access_key e <nome>_secret_key — os mesmos dois secrets que secret set já grava. --credentials-ref é conflicts_with --access-key/--secret-key (o clap recusa as duas formas juntas, exit 2). A referência é resolvida antes de tocar a origem; se não resolver, o erro nomeia a ref, o cofre e os secrets que faltam — nunca um valor. O envelope quick.execute grava credentials_ref (só o nome, nunca o segredo). Motivo: argumentos de linha de comando ficam visíveis em logs e no ps — quando o quick é disparado por outro sistema (agendador, automação), passar a chave por --access-key expõe o segredo. Hoje, como s3/b2 são recusados no quick (ver aviso acima), o efeito prático de --credentials-ref fica para quando esse caminho for ligado aos drivers reais de storage/.

# Opções de Backup

# Retenção por Série (desde 0.32.0)

backupally quick /data -d /backups/ -z --series diario --retention-days 7

Depois de um backup bem-sucedido, remove os backups da mesma série com mais de N dias. Com --series, o artefato sai como {série}_{AAAAMMDD_HHMMSS}.tar.gz, em vez do nome padrão {pasta}_{timestamp}.

Regras de segurança da retenção (apagar arquivo em servidor de cliente pede cautela extra):

• --retention-days exige --series — sem série, recusa. O nome padrão colide entre origens homônimas e com backup manual;
• casa por regex ancorada à série: diario_20260101_020000.tar.gz entra, diario_notas.tar.gz e outra-serie_... não;
• idade lida do timestamp no nome (UTC), nunca do mtime do arquivo;
• só roda depois de um backup bem-sucedido desta execução; execução que falha não remove nada, e o backup mais novo da série nunca sai;
• só remove arquivo regular (não segue symlink, não remove diretório);
• só vale para destino local com --zip;
• --series aceita [A-Za-z0-9._-], até 64 caracteres, sem começar com . ou -.

Backups antigos com nome anônimo (sem série) não são removidos — não há como provar a que origem pertencem. O envelope quick.execute ganha data.retention (removed, kept, failed, skipped_reason) quando a retenção é pedida; o campo fica ausente quando não é.

# Artefato Descrito no Envelope (desde 0.34.0)

quick.execute -o json passa a descrever o que foi gravado: artifact_path, bytes_total e sha256 — lidos do arquivo final, no disco, depois do rename/cópia para o destino (o mesmo que sha256sum <artifact_path> devolveria):

• com -z/--zip: caminho do .tar.gz, tamanho e SHA-256 do arquivo;
• sem -z: caminho do diretório e soma dos bytes, sem sha256 (diretório não tem hash com definição única);
• background (-b) e erro omitem esses campos — não mandam null, para não confundir consumidor antigo.

{
  "success": true,
  "command": "quick.execute",
  "data": {
    "artifact_path": "/backups/diario_20260919_030000.tar.gz",
    "bytes_total": 15890432,
    "sha256": "a1b2c3d4e5f6..."
  }
}

# Exemplos

# Backup Local Simples

backupally quick /var/www/html -d /backups/

# Backup Compactado

backupally quick /var/www/html -d /backups/ -z

# Backup com Nome Customizado

backupally quick /data -d /backups/ -z -n daily_backup

# Backup em Background

backupally quick /data -d /backups/ -z -b

# Backup com Retenção por Série

backupally quick /data -d /backups/ -z --series diario --retention-days 7

# Backup com Credencial por Referência

backupally quick /data -d /backups/ -z --credentials-ref minha-nuvem

# Backup para AWS S3 ou Backblaze B2

-t s3/-t b2 recusam no quick (desde 0.34.1 — ver "Opções de Storage" acima). Para nuvem, crie uma task com [[storage]] s3/b2.

# Saída

O comando exibe:

• Progresso do backup
• Tamanho original e comprimido
• Tempo de execução
• Caminho do arquivo gerado

# Notas

• Use quick para backups pontuais ou testes
• Para backups recorrentes, ou para gravar em s3/b2, crie uma task
• -t s3/-t b2 são recusados no quick (desde 0.34.1); só local funciona
• Veja `--capabilities` para o que o binário instalado sabe fazer de verdade