Pular para o conteúdo
dotby Docs

Use a CLI

O comando dotby coloca o seu espaço de trabalho no terminal. Crie uma tarefa sem sair da branch em que você está, veja o que está atribuído a você ou deixe um script fazer cem dessas coisas de uma vez.

Ele é um cliente fino da API REST: tudo o que ele faz, faz como você e com as suas permissões. Não existe conta separada para a CLI, nem token com superpoderes.

Instale

Section titled “Instale”

A CLI é distribuída como pacote npm que já carrega o binário da sua plataforma. Não há script de postinstall, então ela também instala com --ignore-scripts, que é como CI e sandboxes de agentes costumam rodar.

Terminal window
npm i -g dotby-cli

O pacote se chama dotby-cli; o comando que ele instala é dotby.

Faça login

Section titled “Faça login”

  1. Na sua máquina, deixe o navegador abrir:

    Terminal window
    dotby auth login
    dotby auth status

    A sessão se renova sozinha, e as credenciais vão para o keychain do sistema — nunca para o repositório.

  2. Em um script, em um job de CI ou em um agente não há navegador. Crie um token de acesso pessoal no app, em Configurações → Chaves de API, e envie ele pela entrada padrão:

    Terminal window
    printf %s "$DOTBY_PAT" | dotby auth login --with-token

    Definir DOTBY_TOKEN no ambiente também funciona, e tem prioridade sobre qualquer credencial guardada.

Nunca passe um token como valor de opção ou argumento. Ele iria parar no histórico do shell e na lista de processos de qualquer usuário da máquina.

Aponte para um espaço de trabalho

Section titled “Aponte para um espaço de trabalho”

Todo comando precisa saber com qual espaço de trabalho está falando, e a maioria precisa de um projeto. Responda isso uma vez por repositório:

Terminal window
dotby init

Isso gera um .dotby.toml que você versiona, para que todo o time herde o mesmo contexto:

workspace = "acme"
project = "ENG"

Quando quiser saber o que está realmente valendo — e de onde veio cada valor — pergunte:

Terminal window
dotby context

A precedência é: opção --workspace → DOTBY_WORKSPACE → o .dotby.toml mais próximo → a sua configuração de usuário. O que você passa na linha de comando sempre vence.

Comandos do dia a dia

Section titled “Comandos do dia a dia”

A gramática tem no máximo dois níveis: um substantivo e depois um verbo. --help funciona em qualquer um deles.

Terminal window
dotby issue list --state-bucket started
dotby issue view ENG-42 --include description
dotby issue create --title "Corrigir redirecionamento de login" --priority high
dotby issue move ENG-42 --state <stateId>
dotby issue comment ENG-42 -b "Publicado em staging"
dotby search "redirecionamento de login"

Uma tarefa é endereçada do jeito que você fala: ENG-42. Projetos vão pela chave (ENG) e espaços de trabalho pelo slug. Ids também funcionam em toda parte, tanto na leitura quanto na escrita.

Leia a partir de um script

Section titled “Leia a partir de um script”

A saída padrão carrega dados e nada mais — progresso, dicas e erros vão para a saída de erro, então um pipe nunca engole algo que você precisava ler.

Terminal window
dotby issue list --json=identifier,title,state   # escolha os campos
dotby issue list --json                          # lista os campos disponíveis
dotby issue list --jq '.[].identifier'           # filtra na hora

O --jq roda no próprio processo, então não há binário jq para instalar antes.

Dentro do CI ou de um agente — ou sempre que a saída for redirecionada — a CLI deixa de colorir, para de cortar texto e nunca pergunta nada.

Ensaie uma escrita

Section titled “Ensaie uma escrita”

Toda mutação aceita --dry-run: ela mostra a requisição que enviaria, não muda nada e sai com 0. Não precisa de rede nem de credencial, o que a torna segura para rodar em um teste.

Terminal window
dotby issue create --title "Corrigir login" --priority high --dry-run
dotby issue archive ENG-42 --yes

O --yes pula as confirmações. Comandos destrutivos precisam dele em qualquer sessão não interativa, porque a CLI se recusa a perguntar onde ninguém pode responder.

Códigos de saída

Section titled “Códigos de saída”
Código Significado
0 Tudo certo
1 Algo falhou
2 Opções erradas, argumentos faltando ou nenhum espaço de trabalho no contexto
3 A tarefa, o projeto ou o espaço de trabalho não existe
4 Login não feito ou token recusado

É isso que torna a CLI programável: “crie se não existir” vira um case, não uma comparação de texto.

Terminal window
dotby issue view "$KEY" --json= >/dev/null 2>&1
case $? in
  0) echo "existe" ;;
  3) dotby issue create --title "$TITLE" ;;
  4) echo "precisa de login" >&2; exit 1 ;;
esac

Com --json, uma falha também imprime um envelope legível cujo hint é exatamente o comando que resolve o problema.

Crie várias de uma vez

Section titled “Crie várias de uma vez”

Envie um objeto JSON por linha na entrada padrão. A CLI agrupa tudo em lotes e devolve um resultado por item, então uma falha parcial diz exatamente qual linha falhou.

Terminal window
dotby bulk create --priority medium <<'EOF'
{"title":"Configurar CI"}
{"title":"Corrigir redirecionamento de login","priority":1}
{"title":"Escrever documento de onboarding"}
EOF

Todo o resto

Section titled “Todo o resto”

Os comandos cobrem o caminho do dia a dia. Para o restante da API — membros, apontamentos de horas, iniciativas, páginas, sprints — chame direto:

Terminal window
dotby api GET /me
dotby api GET '/workspaces/acme/issues/mine?tab=assigned'
echo '{"name":"Lançamento do Q3"}' | dotby api POST /workspaces/acme/initiatives

Os caminhos partem de /v1. Autenticação, novas tentativas e tratamento de erro continuam valendo, então este é um atalho, não um downgrade.