Manual do Berth

SFTP · Terminal · Console serial em uma única janela — de adicionar um servidor aos atalhos

🚀Primeiros passos

Estrutura da tela

Uma janela, quatro áreas.

• Barra lateral de sites — à esquerda. Servidores, consoles seriais e pastas aparecem em uma árvore.
• Coluna de sessões — as sessões conectadas. Uma faixa colorida indica de qual servidor é cada uma.
• Área de trabalho — acima ficam os painéis de arquivos (local e remoto), abaixo o terminal. Arraste a linha divisória para mudar a proporção.
• Barra de status — na parte inferior. Mostra o que está acontecendo no momento.

Adicionando o primeiro servidor

1. Clique com o botão direito em um espaço vazio da barra lateral, ou pressione ⌘N.
2. Digite o nome e o endereço do servidor. Usuário e porta podem ficar em branco — os valores padrão são usados.
3. Clique duas vezes na lista para conectar. Um clique é apenas seleção.

Mudar o idioma

No menu Berth › Ajustes (⌘,), escolha um entre 20 idiomas. O padrão é seguir o idioma do sistema, e o idioma escolhido se aplica somente a este app. A mudança entra em vigor ao reiniciar o app.

🗂Servidores e pastas

Agrupar em pastas e herdar

Ao agrupar servidores em uma pasta (⌘⇧N), as configurações descem para eles. Definir o usuário ou a classificação de atenção uma vez na pasta faz todos os servidores abaixo dela seguirem esse valor. É o recurso que evita escrever o mesmo valor vinte vezes para vinte servidores.

Cada campo da janela de configurações mostra abaixo de onde veio aquele valor (definido por você ou herdado de alguma pasta), e um botão de reverter volta para o valor herdado.

Classificação de atenção — Desenvolvimento · Staging · Produção

O nível prevalece sobre a cor. Em Produção, as ações arriscadas pedem confirmação extra. Na lista de sessões é preenchida com a cor que você escolher e marcada com uma borda vermelha, então vários servidores de produção continuam distinguíveis pela cor. Onde apenas um aparece de cada vez (diálogos de confirmação e afins), permanece vermelho como aviso forte.

Regras de clique

• Um clique — seleciona (para ver ou mover as configurações)
• Dois cliques — em servidor, conecta; em pasta, expande/recolhe
• O triângulo antes da pasta expande com um clique.

🔑Conexão e autenticação

Na primeira conexão — permissão de pasta

O Berth segue as regras da App Store (sandbox) e não lê a pasta pessoal livremente. Na primeira vez que um servidor é aberto, o app pede para escolher, de uma vez, a pasta com a configuração SSH, as chaves e o known_hosts (geralmente ~/.ssh). Escolhida uma vez, ela é lembrada e não é pedida de novo. Se as chaves estiverem em outro lugar, também é possível escolher a pasta pessoal.

Pelo mesmo motivo, o painel de arquivos local também usa a pasta escolhida por você como raiz — é possível trocá-la em Abrir pasta local, no cabeçalho do painel, e essa escolha também é lembrada.

Lê o ~/.ssh/config

Ao conectar por um alias, o host, a porta, o usuário, o arquivo de chave, ProxyJump e StrictHostKeyChecking daquele bloco são lidos e usados. Mesmo que a porta salva esteja desatualizada, o arquivo de configuração prevalece.

Método de autenticação

• Automático — deixa a critério do ssh. Todas as chaves padrão são tentadas e, se nenhuma funcionar, a senha é pedida no terminal.
• Arquivo de chave — usa só a chave indicada.
• Senha — pula as chaves.

Quando o servidor pergunta

Com a senha salva, ela é usada automaticamente uma vez ao conectar. As demais perguntas — código de verificação em duas etapas, nova tentativa após senha errada, senha de uma chave protegida — aparecem na janela "O servidor enviou uma solicitação", exatamente como o servidor perguntou, para você responder diretamente. Para não bloquear a conta, a senha salva é preenchida automaticamente só uma vez, e no máximo três perguntas são feitas.

Parar de digitar a senha toda vez

Clique com o botão direito no servidor e escolha Registrar chave pública neste servidor… para enviar a chave pública de ~/.ssh ao servidor. A partir daí, a conexão passa a usar a chave.

A senha salva fica somente no Chaveiro do macOS. No arquivo de configuração fica apenas a marca de "está salva", o valor em si não é gravado ali.

Servidor desconhecido, chave do host alterada

Na primeira conexão com um servidor, o tipo e a impressão digital da chave são mostrados, e o app pergunta se deve lembrar. Se sim, o registro é gravado em ~/.ssh/known_hosts no mesmo formato do ssh, e não é pedido de novo.

Também aparece quando a identidade do servidor é diferente da última vez. Pode ser um ataque man-in-the-middle ou apenas o servidor reinstalado. O Berth não decide por você — dá os elementos: o tipo e a impressão digital das chaves antiga e nova, além do comando para conferir diretamente no console do equipamento. Depois de confirmar, ao clicar em "Apagar a chave antiga e lembrar a nova", o registro antigo é removido (com backup em known_hosts.old) e a nova chave é gravada.

Painel de arquivos (SFTP)

Enviar e trazer

À esquerda fica o seu Mac, à direita o servidor. Arraste e solte, ou use ⌥⌘→ (enviar) e ⌥⌘← (trazer). O andamento se acumula na linha de transferências.

Painel de arquivos que acompanha o terminal

Ao dar cd no terminal, o painel remoto acompanha para a mesma pasta. Quando esse acompanhamento atrapalha, desative com ⌘⇧L.

Locais frequentes · Visualização

• ⌘D — fixa ou solta o caminho atual como pino. O pino se torna a raiz da árvore.
• ⌘↓ — entra na pasta selecionada. ⌘↑ volta um nível.
• ⌥⌘T — árvore ↔ lista. Em pastas com milhares de arquivos, a lista é melhor.
• ⌘R — reler.
• ⌘⇧F — Procurar no servidor. Não é o app que percorre a lista; é o servidor que roda find.

Ver diferenças

Ativando com ⌘⇧Y, local e remoto são comparados lado a lado, mostrando o que é diferente e o que existe só de um lado. Útil quando se quer enviar apenas o necessário.

Excluir

⌘⌫ por padrão move para a lixeira do lado do servidor e sempre pede confirmação. Em servidores com a lixeira desativada, o app avisa antes que a ação não pode ser desfeita.

⌨️Terminal

É um shell de verdade, onde vim, tmux e less rodam normalmente. Selecione arrastando com o mouse e copie com ⌘C: o comando é colado limpo, sem os espaços de preenchimento no fim da linha.

Confirmação ao colar

Ao colar várias linhas, o app mostra antes o que vai ser executado. Isso porque um texto colado com quebras de linha vira comandos ali mesmo. Trechos que parecem arriscados aparecem com o motivo.

Visualização ampla

⌘↩ amplia a área atual; pressione de novo para voltar. ⌥⌘↩ amplia só um painel. O tamanho do texto é ⌘+ · ⌘- · ⌘0. Limpe o terminal com ⌘L — a tela e o histórico de rolagem são apagados, restando apenas a linha de comando atual.

🔌Console serial (UART)

Escolher o dispositivo

Adicione um console serial com ⌃⌘N e escolha nas configurações o dispositivo conectado. O Berth não guarda o caminho, e sim o dispositivo — pelo número de série quando existe, ou pelo tipo quando não existe. Ao trocar de porta USB, o mesmo dispositivo ainda é encontrado.

Velocidade e configurações da linha

A velocidade pode ser escolhida na lista ou digitada diretamente (valores fora do padrão como 1,500,000 também funcionam — desde que o adaptador os aceite). O padrão é 8N1 · sem controle de fluxo, o valor da maioria dos consoles.

• Controle de fluxo — ative apenas ao usar um cabo de 4 fios (RTS/CTS). Em um cabo de 3 fios, ativar isso trava a comunicação.
• Avançado (paridade · bits) — clique na linha para expandir. Use apenas quando for diferente, como no bootloader do STM32 (8E1).

Bloco de anotações

Na sessão serial, os comandos digitados e as respostas se acumulam à direita com o horário. A entrada nos momentos em que uma senha é pedida fica oculta.

⚡Atalhos

Os atalhos do app sempre incluem ⌘. Combinações com ⌃·⌥ pertencem ao shell e a TUIs (vim·tmux), então o app não as reivindica.

❓Perguntas frequentes

Onde a senha é armazenada?

Fica salva somente no Chaveiro do macOS. No arquivo de configuração fica apenas a marca de "está salva". O Chaveiro é aberto uma única vez, no momento da conexão.

O app coleta dados de uso?

Não. Não há nenhuma instrumentação dentro do app. Não é contado o que é aberto nem a quais servidores você se conecta.

O console serial trava no meio do uso.

É uma característica da linha, causada por comunicação em grande volume em um UART sem controle de fluxo. Com um cabo de 4 fios, ative o controle de fluxo (RTS/CTS) nas configurações; com 3 fios, reduza a velocidade do lado da placa ou divida a saída em partes menores.

É preciso reescrever a configuração de SSH que eu já uso?

Não. Importando de ~/.ssh/config, a conexão usa o próprio alias, e o host, a porta, o usuário, a chave e o ProxyJump daquele bloco são lidos e usados.

Tenho uma configuração que usa ProxyCommand.

ProxyCommand inicia um programa externo, algo que o sandbox da App Store não permite. Se a configuração passa por um host de salto, basta trocar por ProxyJump — o resultado é o mesmo. Pelo mesmo motivo, o ssh-agent também não pode ser usado: a chave é lida diretamente, e chaves protegidas por senha pedem a senha no momento da conexão.

Quais versões do macOS são compatíveis?

macOS 14 (Sonoma) ou posterior, compatível com Apple Silicon e Intel.

Se isso ajudou

O Berth é gratuito. É possível ajudar o desenvolvimento com Apoiar.