Comandos

Todo comando aceita --api-url, --git-url e --org para sobrescrever a configuração resolvida em uma única execução. Comandos que atuam sobre um projeto aceitam --project, -p; se você omitir, a CLI usa o vínculo .harumi gravado por harumi new/import/clone/link (procurado subindo a partir da pasta atual).

Autenticação

harumi login             # conta existente: e-mail + código único
harumi login --signup    # cria a conta primeiro, depois envia o código
harumi whoami            # mostra o usuário atual (e-mail + id)
harumi logout            # limpa a sessão local

Descubra kernels

Os specs de kernel determinam o tamanho de computação e a imagem em que seu código roda. Liste os disponíveis antes de passar --kernel para o run:

harumi specs

Imprime uma tabela com name, display_name, cpu, memory e se o spec exige assinatura. Use o valor de name (ex.: or_python_small, gurobi_python_medium) como argumento de --kernel.

Exemplos

Lista os projetos de exemplo: projetos Harumi prontos dos quais você pode começar uma cópia.

harumi examples

Imprime uma tabela com slug, name e description; --json imprime os mesmos três campos. Passe o slug de um exemplo para harumi new --example. Antes da 0.12.0 eles se chamavam blueprints: harumi blueprints e new --blueprint continuam funcionando, ocultos e com um aviso de descontinuação, até a 0.13.0.

Começando um projeto

Existem três formas de colocar um projeto na sua máquina, uma para cada jornada em Começando um projeto — esta seção cobre as três, além do link e do new --no-clone.

harumi start                                          # pergunta a jornada, então executa um dos comandos abaixo

harumi new "Planejamento de Demanda"                  # nada ainda: cria + clona um scaffold
harumi new "Planejamento de Demanda" --example <slug>    # começa de uma cópia de um exemplo em vez do scaffold padrão
harumi new "Planejamento de Demanda" --dir ./outro-lugar
harumi new "Planejamento de Demanda" --personal       # cria no seu workspace pessoal
harumi new "Planejamento de Demanda" --no-clone       # só cria: sem clonar, sem vincular (para scripts)

harumi import                                         # pasta existente: cria um projeto a partir do diretório atual
harumi import ./meu-projeto --project-name "Novo Nome"
harumi import ./meu-projeto --from-git https://github.com/org/repo.git
harumi import ./meu-projeto --personal

harumi clone <PROJECT_ID>                             # projeto já existente na Harumi: clona + vincula
harumi clone <PROJECT_ID> --dir ./outro-lugar

harumi link --project <PROJECT_ID>                    # já está clonado: só vincula

Novos projetos são criados na organização configurada (veja Configuração), e o new informa em qual workspace o projeto foi criado. new --no-clone provisiona o repositório Gitea do projeto no servidor, mas não toca no seu diretório local nem no git.

new e clone se recusam a clonar em um destino que já existe e não está vazio — passe --dir para escolher outro lugar. new, import e clone terminam gravando .harumi/config.json e configurando o remote git harumi para push via HTTPS + token, a mesma etapa de vínculo que o link executa por conta própria para uma pasta que já está clonada.

Projetos

Liste e gerencie os projetos que você enxerga. (Criar um é o harumi new.)

harumi projects list                                # lista seus projetos
harumi projects get <PROJECT_ID>                    # detalhes de um projeto
harumi projects rename <PROJECT_ID> <NOVO_NOME>     # renomeia um projeto
harumi projects rm <PROJECT_ID>                     # exclui (confirma antes)

projects rm pede para você digitar o nome do projeto para confirmar, a menos que você passe --yes.

Repositório

O repositório de um projeto é um repositório git comum. harumi new, import e clone deixam no seu checkout um remote chamado harumi com seu token já na URL, então o git normal funciona sem nenhuma configuração extra — não existe um comando harumi repo.

A URL do remote harumi embute seu token do Gitea. O git o guarda em .git/config e o git remote -v o imprime, então não cole nenhum dos dois em chats, logs ou issues.

Um commit e um push cobrem qualquer quantidade de arquivos editados. Você não precisa commitar para experimentar: o harumi run envia o trabalho não commitado para uma branch temporária por você.

Verificar se está pronto

harumi check                  # tudo que impede este projeto de rodar
harumi check --ref <branch>   # o mesmo, para outra branch ou commit

O check informa o que impediria o harumi run — o repositório existe, o harumi.toml está presente e válido, e o kernel é um que o projeto pode usar — antes de você rodar.

Files

Envie, liste, baixe e exclua arquivos no armazenamento não-git do projeto — diferente do repositório git do projeto (versionado em git, resulta em um commit): uploads ficam num bucket compartilhado, sob o prefixo próprio do projeto, e aparecem em inputs/ dentro do sandbox de cada execução.

harumi files ls                                  # todo arquivo enviado a este projeto
harumi files put ./data.csv                       # envia como "data.csv"
harumi files put ./data.csv raw/data.csv           # envia para um caminho específico
harumi files get raw/data.csv --output ./data.csv
harumi files rm raw/data.csv --yes
harumi files rm raw/data.csv --yes --missing-ok   # sai com 0 se ele já não existir

Run

harumi run
harumi run --branch <b> --commit <sha> --command <c> --kernel <k> --watch
harumi run --tag prod --watch

Veja O modelo de execução para como as branches temporárias funcionam. Quando uma execução com --watch termina com sucesso, a CLI imprime o comando harumi runs download para baixar o resultado.

Tags

Uma tag é um rótulo móvel para uma versão, como prod. Execute uma com harumi run --tag, ou siga uma de um agendamento com --git-tag. Veja Tags para saber como elas se comportam.

harumi tags list
harumi tags set prod                       # a branch em que você está
harumi tags set prod --to release-2        # outra branch
harumi tags set prod --to 3f2a9c1e         # um commit
harumi tags rm prod --yes

tags set cria a tag, ou a move se ela já existe. Sem --to, marca a branch em que você está e recusa se essa branch tiver commits que o servidor ainda não tem, porque a tag marcaria um código mais antigo do que você vê; faça push antes, ou passe --to. Uma tag não pode ter o mesmo nome de uma branch.

tags rm é recusado enquanto um agendamento segue a tag. Os commits não são afetados.

Execuções (runs)

Inspecione, cancele e baixe execuções passadas e em andamento.

harumi runs list                                 # execuções recentes, mais novas primeiro
harumi runs get <RUN_ID>                          # detalhes + stdout/stderr/erro capturados
harumi runs cancel <RUN_ID>                        # cancela uma execução em andamento
harumi runs download                              # o resultado da execução mais recente, em zip nesta pasta
harumi runs download <RUN_ID> --output-dir ./out   # o resultado de uma execução específica

Comparar execuções

Coloque de 2 a 4 execuções lado a lado: os KPIs declarados pelo projeto, a vencedora e se as execuções usaram as mesmas entradas.

harumi compare <RUN_ID> <RUN_ID>                  # a primeira execução é a referência
harumi compare <RUN_ID> <RUN_ID> <RUN_ID> --json   # a comparação bruta, para scripts

Os KPIs são as declarações [[output.kpi]] do harumi.toml do projeto. A vencedora é a execução com o melhor valor do KPI principal; quando não há vencedora, a saída explica o motivo. "Entradas" informa same (iguais), differs (diferentes, com os arquivos que diferem) ou unknown quando uma execução não tem registro das suas entradas.

Fontes de dados

Conexões de banco de dados por projeto. Estes usam endpoints reais e ativos hoje. As credenciais são sempre solicitadas interativamente (entrada oculta) — nunca passadas como flag — e o servidor nunca as retorna.

harumi datasources list
harumi datasources get <nome>
harumi datasources add <nome> --type postgresql --host <host> --port 5432 --database <db> --username <usuario>
harumi datasources update <nome> --host <novo-host> --set-credentials
harumi datasources query <nome> --sql "SELECT * FROM orders LIMIT 10" --csv ./out.csv
harumi datasources test --type postgresql --host <host> --port 5432 --database <db> --username <usuario>
harumi datasources rm <nome> --yes

Dashboard

Consulte e valide os widgets do dashboard.toml do projeto antes de commitá-lo — a plataforma descarta silenciosamente um widget que não consegue renderizar em vez de gerar um erro, então validar localmente é a única forma de detectar um erro de digitação com antecedência. Veja Widgets para a mesma referência com exemplos mais completos.

harumi dashboard widgets                              # todos os tipos de widget + suas chaves
harumi dashboard widgets --type table                 # apenas um tipo
harumi dashboard validate                              # valida ./dashboard.toml
harumi dashboard validate --against ./output/output.json
harumi dashboard validate --run <RUN_ID>              # valida contra o output de uma execução
harumi dashboard validate --latest                    # valida contra a execução mais recente
harumi dashboard validate --ref <branch>              # valida a cópia do repositório em vez de um arquivo local

dashboard validate reporta todo widget que a plataforma descartaria (tipo desconhecido, chave obrigatória ausente) e, quando --against/--run/--latest é passado, sinaliza dot-paths que não resolveriam contra aquele output.json.

Compartilhamento

Gerencie os links públicos e não autenticados do dashboard de um projeto. Um projeto pode ter vários links, cada um revogável de forma independente, cada um com suas próprias permissões e senha opcional. Toda permissão vem desativada por padrão em add, então criar um link nunca concede silenciosamente mais do que uma visualização somente leitura do dashboard, limitada à execução mais recente. As capacidades de run-control exigem adicionalmente que o visitante esteja autenticado. rotate e a troca da senha invalidam as sessões de visualização emitidas anteriormente apenas para aquele link.

harumi share list                                 # todos os links deste projeto
harumi share get <LINK_ID>                        # URL completa e permissões de um link
harumi share add                                  # cria um link (todas as permissões desativadas)
harumi share add --label "Cliente" --chat --run-history
harumi share add --label "Cliente" --run-history --comparisons   # --comparisons exige --run-history
harumi share update <LINK_ID> --run-control       # só as flags passadas são alteradas
harumi share update <LINK_ID> --disable           # desativa um link sem alterar suas permissões
harumi share rm <LINK_ID> --yes                   # exclui permanentemente
harumi share rotate <LINK_ID>                     # invalida o token atual, gera um novo
harumi share rotate <LINK_ID> --yes               # pula o prompt de confirmação
harumi share update <LINK_ID> --password          # solicita a senha duas vezes (oculta, mín. 8 caracteres)
harumi share update <LINK_ID> --no-password       # torna o link livremente visível novamente

Agendamentos

Agendamentos cron por projeto. O cron é uma expressão bruta de 5 campos interpretada em UTC e validada no servidor. Não há flag de pausar/habilitar — exclua o agendamento para pará-lo.

harumi schedules list
harumi schedules get <SCHEDULE_ID>
harumi schedules add --cron "0 9 * * *" --git-branch main --kernel or_python_small --email-to everyone
harumi schedules add --cron "0 9 * * *" --git-tag prod
harumi schedules update <SCHEDULE_ID> --cron "0 6 * * 1-5"
harumi schedules rm <SCHEDULE_ID> --yes

Secrets

Variáveis de ambiente por projeto, injetadas nos seus kernels na execução. Os valores são armazenados com segurança e nunca são exibidos. Definir um nome existente o sobrescreve.

harumi secrets list                              # apenas nomes (valores nunca exibidos)
harumi secrets set <NOME>                         # solicita o valor (entrada oculta)
harumi secrets rm <NOME> --yes

Memórias

Notas curtas que o assistente do projeto lembra, visíveis para todos com acesso ao projeto. Memórias always são carregadas em todo turno do chat; as on_demand (o padrão) só são buscadas quando são relevantes.

harumi memories list                              # inclui memórias herdadas da organização ou do seu workspace
harumi memories list --query unidades --mode always
harumi memories add "Informe todo valor monetário em USD" --mode always
harumi memories edit <MEMORY_ID> --content "Use unidades métricas"
harumi memories rm <MEMORY_ID> --yes

Memórias herdadas da organização ou do seu workspace pessoal são listadas, mas não podem ser editadas nem removidas a partir de um projeto.

Skills do projeto

Uma skill é um arquivo de instruções reutilizável que o assistente do projeto só carrega quando é relevante. As skills de um projeto são arquivos comuns no repositório, em skills/<slug>/SKILL.md: crie, edite e exclua no seu clone, com seu editor e o git (veja Repositório). A CLI acrescenta o único passo que uma edição de arquivo não faz — instalar um preset da biblioteca de skills da Harumi.

harumi skills library                             # os presets que você pode instalar
harumi skills library --category modeling --query roster
harumi skills add scheduling-modeling             # grava skills/scheduling-modeling/SKILL.md no seu clone
git add skills/scheduling-modeling && git commit -m "Install scheduling-modeling skill" && git push harumi main

O skills add precisa rodar dentro de um clone. Ele só grava o arquivo — faça commit e push para o assistente poder carregá-lo a partir da branch live — e registra source: harumi/<slug> e a version do preset no frontmatter. Ele se recusa a sobrescrever um skills/<slug>/SKILL.md existente, a menos que você passe --force.

Para instalar as skills da própria CLI Harumi em um agente de código, veja Skill de agente.

Organizações

Gerencie as organizações às quais você pertence e seus membros.

harumi org list
harumi org create "<NOME_DA_EMPRESA>"
harumi org rename <ORG_ID> "<NOVO_NOME>"
harumi org rm <ORG_ID> --yes
harumi org members <ORG_ID>
harumi org invite <ORG_ID> --email pessoa@exemplo.com --role member
harumi org role <ORG_ID> <USER_ID> --role admin
harumi org rm-member <ORG_ID> <USER_ID> --yes
harumi org use <ORG_ID>                          # persiste a org enviada como X-Organization

Perfil

harumi whoami            # mostra seu perfil, o ambiente e a organização ativa
harumi profile set --first-name Ana --last-name Silva --bio "Engenheira de otimização"

Uso

Sua cota de créditos atual (ou de uma --org) — veja Preços e Limites para o que é um crédito e o que cada plano inclui.

harumi usage                  # sua cota pessoal
harumi usage --org <ORG_ID>   # a cota agrupada de uma organização

Imprime o código do plano, o saldo, os créditos incluídos e quando o período é renovado. Se o excedente estiver ativado, também mostra o limite de gastos; caso contrário, avisa que a próxima mensagem de chat ou execução com saldo zero é um bloqueio total (HTTP 402).

Status da plataforma

O status ao vivo de cada parte da plataforma Harumi, lido da página de status pública. Não exige login.

harumi status

Imprime uma tabela de serviços (group, service, status) e sai com código diferente de zero se algum serviço estiver fora do ar, então também funciona em scripts. Segue o ambiente ativo (veja Ambientes). Quando um comando falha porque a Harumi não pôde ser alcançada, ou responde com erro 5xx, a mensagem de erro da CLI aponta para cá.

Novidades da versão

harumi whats-new          # notas de versão da versão que você tem instalada
harumi whats-new --all    # todas as versões, da mais nova para a mais antiga

As notas vão dentro do pacote, então isso funciona offline. As mesmas notas estão na página Changelog.

A harumi também avisa quando há uma versão nova: depois de um comando, em um terminal interativo, ela imprime um aviso de uma linha com o comando de atualização para o jeito como você instalou. Ela verifica no máximo uma vez por dia e repete o mesmo aviso no máximo uma vez por dia. Nada é impresso quando a saída é redirecionada, sob CI ou em harumi --version; defina HARUMI_NO_UPDATE_CHECK=1 para desligar.

Ambientes

A CLI se conecta a um ambiente de backend — production é o padrão e o único visível para usuários comuns.

harumi env list          # ambientes selecionáveis e seus endpoints (o ativo é sinalizado)
harumi env list --all    # inclui ambientes internos (somente VPN)
harumi env use <nome>    # persiste um ambiente padrão diferente
harumi --env <nome> run  # sobrescreve o ambiente em um único comando

Cada ambiente mantém sua própria sessão de login, então trocar com env use não desconecta você do outro — ainda é preciso rodar harumi login ao menos uma vez por ambiente. A equipe da Harumi tem ambientes internos adicionais disponíveis; eles ficam ocultos em env list a menos que você passe --all.

Configuração

Cada configuração é resolvida nesta ordem: flag da CLI > variável de ambiente > config em ~/.harumi > padrão.

harumi org use <ORG_ID>   # persiste a org enviada como X-Organization

A organização define quais projetos o projects list retorna, e é o workspace em que new e import criam novos projetos. Passe --personal em qualquer um deles para criar um projeto no seu workspace pessoal.

Defina HARUMI_HOME para mudar a pasta de configuração inteira (credenciais, config e tokens ficam todos sob ela).

Skill de agente

Instale as skills de agente harumi-cli e harumi-cli-setup incluídas nesta máquina (não confunda com as skills do próprio projeto) — veja Skill de agente para o que elas fazem e os outros métodos de instalação (npx skills, o marketplace de plugins do Claude Code/Cursor).

harumi agent-skills install            # detecta agentes instalados, escopo global
harumi agent-skills install --project  # grava em ./.agents/skills em vez disso
harumi agent-skills install --agent claude-code --dry-run   # imprime cada origem -> destino, sem gravar

Renomeados na 0.11

Os nomes antigos continuam funcionando na 0.11.x — ocultos do --help, e cada um imprime uma linha deprecated: com o substituto — e são removidos na 0.12.0.

Arquivos usados pela CLI

• ~/.harumi/environments/production/credentials.json — tokens de sessão e o token do Gitea (modo 0600).
• ~/.harumi/environments/production/config.json — org_id resolvido (e quaisquer overrides locais de api_url/git_url).
• <projeto>/.harumi/config.json — vínculo do projeto por pasta (project_id + repo), procurado subindo a partir da pasta atual.

Biblioteca Python

A mesma funcionalidade está disponível como biblioteca — útil em notebooks ou na sua própria automação.

from harumi import Client
from harumi.config import ProjectBinding

binding = ProjectBinding.load()   # lê .harumi/config.json
client = Client()                 # lê sua sessão armazenada

response = client.execute_project(
    binding.project_id,
    branch="feature/solver-v2",
    command="python main.py",
)

from harumi.execution import wait_for_run, download_run_output
result = wait_for_run(client.api, binding.project_id, response.project_run_id)
print(result.status, result.succeeded)

download_run_output(client.api, binding.project_id, result, "./out")