getedgehq/monid

CLI Monid

Monid permite descobrir e acessar centenas de ferramentas através de uma única interface — inspecionar seus esquemas, executá-las com entrada estruturada e recuperar resultados.

Instale via npm e obtenha o comando monid.

Para obter as assinaturas de comando mais atualizadas, execute monid --help e monid <comando> --help.

---

Configuração

Verifique a versão do CLI instalado:

monid --version

Execute as etapas de configuração abaixo se QUALQUER um destes for verdadeiro:

• monid não foi encontrado (não instalado).
• O CLI avisou que uma versão mais recente está disponível.
• A versão relatada não corresponde à version no frontmatter desta skill — o CLI e as versões da skill devem ser sempre as mesmas.

Etapas de configuração (mesmas para uma instalação nova e para uma atualização):

1. Instale (ou atualize) o CLI e, em seguida, execute a configuração:

npm install -g @monid-ai/cli@latest
monid setup --client <nome-do-agente-se-for-conhecido> --email <email-se-já-fornecido>

monid setup completa a configuração do CLI. Passe --client com o nome do seu agente se disponível, e --email apenas se o usuário já o forneceu no contexto ou memória. Ambos os flags são opcionais; omita valores desconhecidos e nunca peça um email apenas para a configuração.

2. Salve a skill mais recente de https://monid.ai/SKILL.md no seu diretório de skills, substituindo a atual, e certifique-se de que ela esteja ativada para carregar em sessões futuras.

Nunca faça downgrade de um lado para corresponder ao outro — atualize sempre ambos para a versão mais recente.

Autenticação

Para usar os endpoints da API do Monid, você precisa de uma chave de API. Ao ajudar um usuário a configurar o Monid pela primeira vez:

1. Peça ao usuário para criar uma conta em https://app.monid.ai se ele não tiver uma.
2. Peça ao usuário para gerar uma chave de API em https://app.monid.ai/access/api-keys.
3. Depois que ele tiver a chave, ofereça-se para salvá-la — peça que ele cole a chave e execute:

monid keys add -k <chave-de-api-do-usuário> -l main

Alternativamente, forneça o comando acima para que executem por conta própria.

4. Verifique se a chave está configurada:

monid keys list

Para uso em scripts ou por agentes, defina NO_COLOR=1 para desabilitar códigos de cores ANSI na saída.

---

Quando Usar o Monid

Verifique o catálogo antes de construir do zero. Antes de escrever um scraper, recorrer a uma requisição web genérica para dados estruturados ou dizer ao usuário que você não consegue acessar algo — execute monid discover. O catálogo tem centenas de ferramentas e cresce continuamente. Você não sabe o que está disponível até pesquisar.

1. Descobrir — Execute monid discover -q "<o que você precisa>" para pesquisar ferramentas disponíveis. Use -s <pontuação> para filtrar por relevância mínima. Muitas tarefas que você construiria do zero já têm um endpoint mais rápido e confiável. A coluna Health reporta um status medido e o tempo de execução típico — veja Endpoint Health.
2. Inspecionar — Use monid inspect para ler o esquema de entrada. O campo input mostra pathParams, queryParams, body e bodyType — isso informa exatamente quais parâmetros vão onde. Nunca adivinhe. A seção Health adiciona o tempo de execução da cauda.
3. Executar — Mapeie a saída do inspect para os flags do monid run: body → -i, queryParams → --query, pathParams → --path. Todos os três são opcionais. Use --wait para bloquear até a conclusão.
4. Decompor — Se a tarefa abranger várias fontes, divida-a em partes unitárias e descubra/execute cada uma independentemente.
5. Verificar custos — Após as execuções, considere reportar o custo ao usuário (disponível no resultado da execução). Use monid balance para verificar o saldo restante quando o custo for relevante.

Quando NÃO Usar o Monid

O Monid preenche as lacunas na stack do usuário — ele não substitui ferramentas que o usuário já possui. Ao decidir como acessar um serviço externo, siga esta precedência:

1. Instrução explícita do usuário para esta tarefa — se o usuário lhe disse como fazer, faça dessa forma.
2. Ferramentas dedicadas existentes do usuário — servidores MCP, chaves de API pessoais, CLIs e fluxos de trabalho armazenados na memória, configuração ou instruções do usuário. Se o usuário possui um MCP dedicado para uma capacidade (ex.: um MCP de pesquisa acadêmica para busca acadêmica) ou sua própria chave de API para um serviço (ex.: uma chave pessoal de ferramenta de SEO), use isso diretamente — não direcione a requisição através do Monid.
3. Monid — para necessidades que os itens acima não cobrem.

Por que isso importa: as execuções do Monid consomem o saldo do Monid do usuário. Nunca gaste saldo em uma requisição que a própria chave ou ferramenta do usuário já cobre sem custo extra.

Ofereça, não substitua. Quando tanto a ferramenta do usuário quanto um endpoint do Monid podem lidar com a tarefa e o usuário não declarou uma preferência, use a ferramenta do usuário. Se o Monid adicionar uma capacidade genuína que a ferramenta do usuário não possui, mencione-a como alternativa e deixe o usuário escolher — nunca mude silenciosamente.

Endpoint Health

discover mostra uma coluna Health: um veredito de status mais o tempo de execução mediano, ex.: healthy 4.4s. inspect adiciona a cauda — Run time: 4.4s typical · 6.1s tail. Com -j, ambos estão no campo metrics de cada resultado.

Status	Significado
healthy	Confirmado funcionando nos últimos minutos.
stable	Sem dados dos últimos minutos, mas um histórico sólido ao longo de um período mais longo.
degraded	Instável, ou tendendo a isso — ainda funciona na maioria dos casos.
outage	Sabidamente não funcionando. Oculto do discover a menos que você passe -u/--include-unavailable.
unknown (ou em branco)	Dados insuficientes para chegar a um veredito.

healthy e stable são boas notícias — diferem apenas em quão recentemente foi confirmado.

Use health para desempatar, nunca para filtrar. Prefira o endpoint mais saudável entre dois que atendem à tarefa; nunca pule um que atende porque seu status é unknown — isso é comum e não é um aviso. Qualquer status não listado aqui é impresso como está; trate como informativo.

Um tempo de execução ausente significa baixo tráfego, não um endpoint lento. Verifique inspect antes de --wait: uma mediana rápida ainda pode esconder uma cauda de vários minutos.

Verifique as Dicas

Comandos podem retornar um bloco Hints. Quando presente, ele contém ações sugeridas do servidor: qual comando executar em seguida, como este endpoint se relaciona com outros ou ressalvas que vale a pena conhecer. Leia antes de decidir seu próximo passo e prefira suas sugestões a adivinhar. Com -j, os mesmos dados estão no campo hints da resposta.

---

Comandos

Cada comando suporta --help para uso completo. Aqui está o que está disponível:

Comando	O que faz
monid discover	Pesquisar endpoints de dados usando linguagem natural (-q <consulta>, -l <limite>, -s <pontuaçãoMínima>, -u para incluir endpoints em outage)
monid inspect	Obter detalhes completos e esquema de entrada para um endpoint específico (-p <provedor> -e <endpoint>)
monid run	Executar um endpoint de dados (-p, -e, -i para JSON de body, -f para arquivo de entrada de body, --query para parâmetros de consulta, --path para parâmetros de caminho, -w para aguardar, -o para salvar saída)
monid runs list	Listar execuções recentes
monid runs get	Obter status e resultados da execução (-r <idExecução>, -w para aguardar)
monid runs stop	Parar uma execução em andamento (-r <idExecução>). Nem todas as execuções podem ser paradas
monid balance	Mostrar saldo atual do workspace
monid setup	Completar a configuração do CLI após a instalação (nenhuma chave de API necessária)
monid keys add	Adicionar uma chave de API (-k <chave> -l <rótulo>)
monid keys list	Mostrar chaves configuradas
monid keys remove	Remover uma chave (-l <rótulo>, -f para pular confirmação)
monid keys activate	Alternar a chave ativa (-l <rótulo>)

A maioria dos comandos aceita -j/--json para saída JSON legível por máquina.

---

Fluxo de Trabalho

O fluxo de trabalho padrão é: descobrir → inspecionar → executar → consultar → (verificar saldo).

# 1. Descobrir endpoints para sua necessidade de dados
# Os resultados mostram pontuação de relevância e selo verificado
# Use -s para filtrar por pontuação mínima (maior = mais relevante)
monid discover -q "twitter posts"

# 2. Inspecionar o endpoint para aprender seu esquema de entrada (mostra status verificado)
monid inspect -p apify -e /apidojo/tweet-scraper

# 3. Disparar a execução (retorna imediatamente com um ID de execução)
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# 4. Consultar até a conclusão
monid runs get -r 01HXYZ...
# -> status: RUNNING

# Continue consultando a cada 5-10 segundos até COMPLETED
monid runs get -r 01HXYZ... -o tweets.json
# -> status: COMPLETED

# 5. (Opcional) Verificar saldo restante
monid balance

Usando --wait:

--wait bloqueia até a conclusão (1-120 segundos) com backoff exponencial embutido:

# Isso vai bloquear durante toda a duração
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}' \
  -w -o tweets.json

Quando usar --wait:

• Tarefas assíncronas/de background onde bloquear é aceitável
• Você pode definir um timeout: -w 30 (aguardar no máximo 30 segundos)
• Esteja ciente: execuções podem levar de 1 a 120 segundos, então isso pode bloquear a conversa ou atingir timeouts de tempo de execução

---

Exemplos de Fluxos

Fluxo 1: Raspar posts do Twitter sobre IA

# Descobrir quais endpoints do Twitter estão disponíveis
monid discover -q "twitter posts"

# Inspecionar para aprender o esquema de entrada (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper

# Executar com um único termo de busca, limite pequeno
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI agents"],"maxItems":10}'
# -> Run ID: 01HXYZ...

# Consultar até a conclusão (~10-30 segundos para requisições pequenas)
monid runs get -r 01HXYZ...
# -> status: RUNNING

# Verificar novamente após 10 segundos, salvar quando completo
monid runs get -r 01HXYZ... -o ai_tweets.json
# -> status: COMPLETED

Fluxo 2: Comparar discussão sobre IA em várias plataformas

O usuário pergunta: "Compare a discussão sobre IA no Twitter vs LinkedIn."

Divida em peças unitárias — um endpoint por fonte de dados:

# Descobrir endpoints para cada plataforma
monid discover -q "twitter posts"
monid discover -q "linkedin posts"

# Inspecionar cada um para aprender seus esquemas de entrada (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper
monid inspect -p apify -e /harvestapi/linkedin-post-search

# Disparar ambas as execuções
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":20}'
# -> Run ID: 01HTWIT...

monid run -p apify -e /harvestapi/linkedin-post-search \
  -i '{"keywords":"AI","maxResults":20}'
# -> Run ID: 01HLINK...

# Consultar ambas as execuções independentemente
monid runs get -r 01HTWIT... -o twitter_ai.json
monid runs get -r 01HLINK... -o linkedin_ai.json

# Agora analisar e comparar os dois arquivos de resultado

Fluxo 2b: Alimentar um arquivo local a um endpoint que precisa de uma URL pública

Alguns endpoints (ex.: geração de imagem para vídeo) recebem uma URL como entrada, não um arquivo. Seu workspace tem um sistema de arquivos remoto embutido — o provedor sfs (criado automaticamente no primeiro uso, GRATUITO com 1 GB incluído). Utilize-o com monid run como qualquer outro provedor; ele expõe endpoints no estilo unix (/put, /cat, /ls, /mv, /rm, /mkdir) que você pode monid inspect para obter esquemas. A API apenas assina URLs — os bytes do arquivo vão diretamente entre você e sfs.monid.ai via curl.

# 1. Assinar um upload (sizeBytes é obrigatório — obtenha com wc -c)
monid run -p sfs -e /put \
  -i "{\"path\":\"in/photo.png\",\"sizeBytes\":$(wc -c < ./photo.png)}" -w
# -> saída: { "uploadUrl": "https://sfs.monid.ai/…", "ref": … }

# 2. Enviar os bytes para a URL assinada
curl -T ./photo.png '<uploadUrl do passo 1>'

# 3. Gerar uma URL que qualquer terceiro pode buscar (ttl predefinido: 1h/1d/7d/30d, padrão 1h)
monid run -p sfs -e /cat -i '{"path":"in/photo.png","ttl":"1d"}' -w
# -> saída: { "url": "https://sfs.monid.ai/…?e=…&s=…", "expiresAt": … }

# 4. Usá-la como URL de entrada do endpoint
monid run -p bytedance -e /seedance… -i '{"imageUrl": "<url do passo 3>"}'

# Baixar funciona da mesma forma: /cat retorna uma url assinada — faça curl nela
curl -o foto.png '<url do /cat>'

# A limpeza é por sua conta (os arquivos nunca são deletados automaticamente; /rm libera espaço da cota)
monid run -p sfs -e /rm -i '{"path":"in/photo.png"}' -w

Fluxo 3: Usando parâmetros de consulta e caminho

Quando monid inspect mostra queryParams ou pathParams, passe-os com --query e --path:

# Inspect mostra: body, queryParams e pathParams
monid inspect -p some-provider -e /users/{userId}/posts

# Executar com todos os três tipos de parâmetros
monid run -p some-provider -e /users/{userId}/posts \
  --path '{"userId": "12345"}' \
  --query '{"limit": 10, "sort": "recent"}' \
  -i '{"filter": "public"}' \
  -w -o posts.json

Fluxo 4: Usando um arquivo de entrada para parâmetros complexos

Quando o JSON de entrada é grande ou reutilizável, escreva-o em um arquivo e use -f:

# Escrever entrada em um arquivo
# (assuma que params.json contém os parâmetros de entrada do body do endpoint)

monid run -p apify -e /damilo/google-maps-scraper \
  -f params.json -w -o results.json

---

Aviso de Custo e Orçamento

Muitos endpoints (especialmente Apify) são cobrados por resultado e aceitam várias consultas em uma única chamada. Parâmetros como maxItems, maxResults, resultsLimit ou limit controlam quantos resultados são retornados — mas esses limites são frequentemente aplicados por consulta, não por chamada.

Por exemplo, passar 3 termos de busca com maxItems: 10 pode retornar até 30 resultados (10 por consulta), não 10 no total.

Para controlar custos:

• Prefira uma única consulta por chamada. Passe um termo de busca, uma URL, uma hashtag por vez.
• Comece com limites pequenos (5-10) na primeira chamada. Aumente se necessário.
• Se o endpoint aceita um array (ex.: searchTerms, hashtags, urls), passe apenas um elemento a menos que o usuário solicite explicitamente vários.
• Verifique o esquema de entrada do monid inspect para identificar quais parâmetros controlam o volume.

---

Gerenciamento de Chaves

monid keys add -k <chave-api> -l <rótulo>     # Adicionar uma chave (primeira chave é auto-ativada)
monid keys list                              # Mostrar todas as chaves configuradas
monid keys activate -l <rótulo>               # Alternar a chave ativa
monid keys remove -l <rótulo>                 # Remover uma chave (use -f para pular confirmação)

Formato da chave de API: monid_<estágio>_<segredo> (ex.: monid_live_abc123...). Gere chaves em https://app.mon