Interfaces
CLI Reference
Referência completa da interface de linha de comando do Arc DevKit — dois entry points: arcdevkit (agrupado) e arc (flat completo).
O Arc DevKit instala dois executáveis de CLI:
| Comando | Entry point | Estilo |
|---|---|---|
arcdevkit | arc_devkit.cli.main:app | Subcomandos agrupados (copilot, agent, debug) |
arc | arc_devkit.cli.flat:app | Comandos diretos — set completo de funcionalidades |
arcdevkit — CLI agrupado
arcdevkit / arcdevkit --version
arcdevkit # exibe banner com versão instalada
arcdevkit --version # imprime somente a versão
arcdevkit -v # alias de --version
arcdevkit status
Verifica a conexão com a rede ativa (mainnet por padrão) e exibe o bloco atual, chain ID e preço do gas. Exibe um aviso vermelho de "fundos reais" em mainnet, ciano em testnet.
arcdevkit status
arcdevkit doctor
Health check somente leitura — alcançabilidade do RPC, correspondência do chain ID, bloco mais recente, latência e se o contrato USDC realmente tem código deployado on-chain. Sai com código diferente de zero se algo falhar.
arcdevkit doctor
arcdevkit copilot
Subcomando do assistente IA baseado no Dev Copilot.
arcdevkit copilot ask
arcdevkit copilot ask PROMPT [--stream] [--json]
| Opção | Alias | Descrição |
|---|---|---|
--stream | -s | Transmite a resposta token a token |
--json | — | Saída JSON com response e model |
Exemplos:
arcdevkit copilot ask "Como crio uma carteira na Arc?"
arcdevkit copilot ask "Gere um contrato ERC-20" --stream
arcdevkit copilot ask "O que é Malachite consensus?" --json
arcdevkit agent
Subcomando para gestão de carteiras e agentes econômicos.
arcdevkit agent create-wallet
Cria uma nova carteira EVM e exibe endereço e chave privada uma única vez.
arcdevkit agent create-wallet
✕Chave privada exibida apenas uma vez
Armazene a chave privada em local seguro imediatamente. Ela não é salva em nenhum arquivo.
arcdevkit agent balance
arcdevkit agent balance ADDRESS
Exibe o saldo da carteira especificada.
arcdevkit agent status
Exibe informações da rede Arc (bloco atual, chain ID, preço do gas).
arcdevkit agent status
arcdevkit agent pay
arcdevkit agent pay TO AMOUNT [--send] [--key KEY]
Prepara (e opcionalmente envia) um pagamento USDC na Arc.
| Argumento/Opção | Descrição |
|---|---|
TO | Endereço EVM do destinatário |
AMOUNT | Valor em USDC |
--send | Transmite a transação na rede (requer ARC_PRIVATE_KEY) |
--key KEY | Chave privada (substitui ARC_PRIVATE_KEY) |
Exemplos:
# Preparar (dry run — não envia)
arcdevkit agent pay 0xDest... 5.0
# Enviar de verdade
arcdevkit agent pay 0xDest... 5.0 --send
# Enviar com chave explícita
arcdevkit agent pay 0xDest... 5.0 --send --key 0xSUACHAVE...
arcdevkit agent monitor
arcdevkit agent monitor ADDRESS [--interval SECS] [--max N]
Monitora uma carteira Arc e exibe alertas quando o saldo muda.
| Opção | Alias | Padrão | Descrição |
|---|---|---|---|
--interval | -i | 15 | Intervalo de polling em segundos |
--max | — | 0 | Iterações máximas (0 = infinito) |
arcdevkit agent monitor 0xCarteira...
arcdevkit agent monitor 0xCarteira... --interval 5 --max 20
Pressione Ctrl+C para parar.
arcdevkit debug
Subcomando para análise e depuração de transações.
arcdevkit debug tx
arcdevkit debug tx TX_HASH [--json]
Analisa uma transação Arc e exibe diagnóstico completo com análise IA.
| Opção | Descrição |
|---|---|
--json | Saída como JSON bruto |
arcdevkit debug tx 0xabc123...
arcdevkit debug tx 0xabc123... --json
arcdevkit debug estimate
arcdevkit debug estimate TO AMOUNT [--from ADDR]
Estima o custo de gas para uma transferência na Arc.
| Argumento/Opção | Descrição |
|---|---|
TO | Endereço EVM do destinatário |
AMOUNT | Valor da transferência em USDC |
--from ADDR | Endereço do remetente (opcional) |
arcdevkit debug estimate 0xDest... 10.5
arcdevkit debug estimate 0xDest... 10.5 --from 0xRemetente...
arcdevkit debug trace
arcdevkit debug trace TX_HASH [--tracer TRACER]
Busca um trace de chamadas internas via debug_traceTransaction, se o RPC suportar. A maioria dos RPCs públicos (incluindo o RPC padrão da Circle para a Arc, em mainnet e testnet) desabilita o namespace debug_* — o comando falha com mensagem clara em vez de erro genérico.
arcdevkit debug compare
arcdevkit debug compare TX_HASH_1 TX_HASH_2
Analisa duas transações lado a lado e destaca as diferenças (status, custo, revert reason).
arcdevkit network
Perfis de rede (mainnet/testnet) e endereços de contrato — ambos já totalmente configurados.
arcdevkit network list
arcdevkit network show mainnet
arcdevkit network check-mainnet
check-mainnet é um dry-run que confirma que nada em NETWORKS["mainnet"] é um placeholder — hoje passa por padrão.
arcdevkit fees
arcdevkit fees quote TO VALUE [--token native|usdc]
Cotação de fee em USDC para transferências nativas ou USDC.
arcdevkit fees quote 0xDest... 5.0
arcdevkit fees quote 0xDest... 5.0 --token usdc
arcdevkit bridge
Bridge cross-chain de USDC via CCTP.
arcdevkit bridge send TO AMOUNT --dest-domain DOMAIN --dest-chain-id CHAIN_ID [--key KEY]
arcdevkit bridge status TRANSFER_ID
arcdevkit bridge resume TRANSFER_ID [--dest-rpc URL --message-transmitter ADDR]
⚠Ainda não validado contra uma transferência real
Endereços do CCTP TokenMessengerV2 já estão publicados tanto para mainnet quanto testnet (a Arc é o domain 26), mas bridge send/resume ainda não foram testados contra um contrato CCTP real da Arc — veja o módulo CCTP Bridge para as limitações conhecidas antes de depender disso em produção.
arcdevkit agent register / reputation / job
Identidade e reputação de agentes (ERC-8004) e marketplace de jobs com escrow (ERC-8183).
arcdevkit agent register DOMAIN --registry ADDR [--key KEY]
arcdevkit agent reputation AGENT_ID --registry ADDR --reputation-registry ADDR
arcdevkit agent job create AGENT_ADDR AMOUNT --spec "..." --registry ADDR [--key KEY]
arcdevkit agent job accept JOB_ID --registry ADDR [--key KEY]
arcdevkit agent job deliver JOB_ID DELIVERABLE --registry ADDR [--key KEY]
arcdevkit agent job settle JOB_ID --registry ADDR [--key KEY]
arcdevkit agent job status JOB_ID --registry ADDR
Nenhum registry canônico ERC-8004/8183 é publicado para a Arc ainda — todo comando exige --registry explícito.
arcdevkit mcp
arcdevkit mcp serve
Roda o Arc DevKit como servidor MCP (requer pip install "arc-devkit[mcp]"), expondo tools read-only para Claude Code e outros clientes MCP.
arcdevkit oracle
arcdevkit oracle price FEED_ADDRESS
Consulta um feed de preço compatível com Chainlink AggregatorV3Interface.
arcdevkit privacy
arcdevkit privacy generate-view-key
arcdevkit privacy encrypt PUBLIC_KEY_HEX "mensagem"
Geração de par de chaves e criptografia view-key para divulgação seletiva (experimental).
arc — CLI flat (set completo)
O executável arc expõe o mesmo conjunto de funcionalidades em comandos diretos (sem grupos aninhados) e adiciona comandos exclusivos: init, codegen, gas, send, history, balance, debug-batch e portfolio.
arc init
Wizard interativo para criar o arquivo .env do zero.
arc init
Solicita interativamente:
ANTHROPIC_API_KEY(obrigatório)ARC_NETWORK(padrão:mainnet)ARC_RPC_URL(override opcional — em branco usa o default oficial da rede)ARC_CHAIN_ID(override opcional — em branco usa o default oficial da rede)ARC_PRIVATE_KEY(opcional)LOG_LEVEL(padrão:INFO)
arc status
arc status [--json] [-v]
arc doctor
Verifica conexão com a rede ativa (mainnet por padrão). Com --json retorna connected, network, chain_id, block_number, gas_price_gwei. arc doctor roda um health check completo e somente leitura (RPC, chain ID, bloco mais recente, latência, presença do contrato USDC).
| Opção | Alias | Descrição |
|---|---|---|
--json | — | Saída como JSON |
--verbose | -v | Ativa logs de debug |
arc ask
arc ask QUESTION [--raw] [--stream] [--json] [-v]
Consulta o DevCopilot — assistente IA especializado em desenvolvimento Arc.
| Opção | Alias | Descrição |
|---|---|---|
--raw | — | Imprime texto puro sem renderização Markdown |
--stream | -s | Transmite resposta token a token |
--json | — | Saída JSON com response e model |
--verbose | -v | Ativa logs de debug |
arc ask "Como funciona o gas em USDC na Arc?"
arc ask "Gere um contrato USDC vault" --stream
arc ask "O que é USDC ERC-20?" --json
arc ask "Explique o Malachite consensus" --raw
arc balance
arc balance ADDRESS [--json] [-v]
Exibe o saldo nativo de USDC (gas) e o nonce de uma carteira.
| Opção | Alias | Descrição |
|---|---|---|
--json | — | Saída JSON com address, balance_arc, nonce |
--verbose | -v | Ativa logs de debug |
arc balance 0xSuaCarteira...
arc balance 0xSuaCarteira... --json
arc gas
arc gas TO AMOUNT [--from ADDR] [--json] [-v]
Estima o custo de gas para uma transferência USDC na Arc.
| Argumento/Opção | Alias | Descrição |
|---|---|---|
TO | — | Endereço EVM do destinatário |
AMOUNT | — | Valor em USDC |
--from ADDR | -f | Endereço do remetente (opcional) |
--json | — | Saída como JSON |
--verbose | -v | Ativa logs de debug |
arc gas 0xDest... 10.5
arc gas 0xDest... 10.5 --from 0xRemetente...
arc gas 0xDest... 10.5 --json
arc debug
arc debug TX_HASH [--abi PATH] [--json] [-v]
Analisa uma transação Arc com diagnóstico IA. Suporte opcional a ABI para decodificar input data.
| Opção | Alias | Descrição |
|---|---|---|
--abi PATH | -a | Caminho para arquivo ABI JSON (opcional) |
--json | — | Saída como JSON bruto |
--verbose | -v | Ativa logs de debug |
arc debug 0xTxHash...
arc debug 0xTxHash... --abi MeuContrato.json
arc debug 0xTxHash... --json
arc debug-batch
arc debug-batch HASHES_FILE [--abi PATH] [--json] [-v]
Analisa múltiplas transações em lote a partir de um arquivo.
| Argumento/Opção | Alias | Descrição |
|---|---|---|
HASHES_FILE | — | Arquivo com hashes (uma por linha ou array JSON) |
--abi PATH | -a | Arquivo ABI JSON para decodificar inputs |
--json | — | Saída como JSON |
--verbose | -v | Ativa logs de debug |
Formato do arquivo (uma hash por linha):
0xabc123...
0xdef456...
0xghi789...
Formato alternativo (JSON array):
["0xabc123...", "0xdef456...", "0xghi789..."]
arc debug-batch hashes.txt
arc debug-batch hashes.json --abi MeuContrato.json --json
arc codegen
arc codegen TOPIC [--save | --no-save] [--out DIR] [-v]
Gera um script Python a partir de uma descrição em linguagem natural. O script é exibido na tela e salvo em arquivo por padrão.
| Opção | Alias | Padrão | Descrição |
|---|---|---|---|
--save / --no-save | — | --save | Salva o script gerado em arquivo |
--out DIR | -o | . (diretório atual) | Diretório de destino do arquivo |
--verbose | -v | — | Ativa logs de debug |
arc codegen "agente que monitora saldo e envia alerta"
arc codegen "contrato ERC-20 simples" --no-save
arc codegen "script de batch payment" --out ./scripts
arc config
Lê e escreve variáveis no arquivo .env.
arc config get KEY # lê uma variável
arc config set KEY VALUE # define uma variável
arc config list # lista todas as variáveis
Exemplos:
arc config get ARC_RPC_URL
arc config set LOG_LEVEL DEBUG
arc config list
arc wallet
Subcomando para gestão básica de carteiras.
arc wallet create
arc wallet create [--json]
Cria uma nova carteira EVM e exibe endereço e chave privada uma única vez.
| Opção | Descrição |
|---|---|
--json | Saída JSON com address e private_key |
✕Chave privada exibida apenas uma vez
Copie e armazene a chave privada imediatamente. Ela não é salva em nenhum arquivo.
arc wallet balance
arc wallet balance ADDRESS [--json]
Exibe o saldo nativo de USDC (gas) de uma carteira.
| Opção | Descrição |
|---|---|
--json | Saída JSON |
arc send
arc send TO AMOUNT [--token TOKEN] [--broadcast] [--yes] [--json] [-v]
Constrói (e opcionalmente transmite) uma transação de pagamento na Arc. Requer ARC_PRIVATE_KEY configurado.
| Argumento/Opção | Alias | Padrão | Descrição |
|---|---|---|---|
TO | — | — | Endereço EVM do destinatário |
AMOUNT | — | — | Valor a transferir |
--token TOKEN | -t | native | native (token de gas USDC) ou usdc (ERC-20) |
--broadcast | -b | False | Transmite a transação (requer ARC_PRIVATE_KEY) |
--yes | -y | False | Pula o prompt de confirmação de mainnet (para scripts/automação) |
--json | — | — | Saída como JSON |
--verbose | -v | — | Ativa logs de debug |
# Construir transação (dry run — não envia)
arc send 0xDest... 5.0 --token native
# Enviar USDC nativo
arc send 0xDest... 1.0 --token native --broadcast
# Enviar USDC ERC-20
arc send 0xDest... 10.0 --token usdc --broadcast
# Pular o prompt de confirmação em automação
arc send 0xDest... 1.0 --broadcast --yes
⚠ARC_PRIVATE_KEY obrigatório para --broadcast
Sem a variável de ambiente ARC_PRIVATE_KEY configurada, o comando encerra com erro. Use arc config set ARC_PRIVATE_KEY 0x... ou defina a variável no .env.
⚠Confirmação de fundos reais em mainnet
Quando a rede ativa é mainnet, --broadcast imprime Network: ARC MAINNET / WARNING: This transaction uses real funds. e pede confirmação interativa antes de enviar — passe --yes para pular em contextos não interativos. A testnet nunca pede confirmação.
arc history
arc history [--limit N] [--json]
Lista análises recentes salvas em ~/.arc_devkit/history.json.
| Opção | Alias | Padrão | Descrição |
|---|---|---|---|
--limit | -n | 10 | Número de registros a exibir |
--json | — | — | Saída como JSON |
arc history
arc history --limit 50
arc history --json
arc portfolio
Análise de carteiras: saldo, histórico de transações e score de atividade.
arc portfolio analyze
arc portfolio analyze ADDRESS [--blocks N] [--no-ai] [--json] [-v]
Analisa uma carteira: saldos (nativo e USDC), transações recentes e insights de IA.
| Opção | Alias | Padrão | Descrição |
|---|---|---|---|
--blocks | -b | 100 | Número de blocos recentes a escanear |
--no-ai | — | — | Pula a análise IA (mais rápido) |
--json | — | — | Saída como JSON |
--verbose | -v | — | Ativa logs de debug |
arc portfolio analyze 0xSuaCarteira...
arc portfolio analyze 0xSuaCarteira... --blocks 500
arc portfolio analyze 0xSuaCarteira... --no-ai --json
O snapshot é salvo automaticamente para histórico.
arc portfolio history
arc portfolio history ADDRESS [--limit N] [--json]
Exibe o histórico de snapshots salvos para uma carteira.
| Opção | Alias | Padrão | Descrição |
|---|---|---|---|
--limit | -n | 10 | Número máximo de snapshots |
--json | — | — | Saída como JSON |
arc portfolio history 0xSuaCarteira...
arc portfolio history 0xSuaCarteira... --limit 30
arc portfolio report
arc portfolio report WALLETS_FILE [--blocks N] [--json] [-v]
Relatório consolidado para múltiplas carteiras a partir de um arquivo JSON.
| Argumento/Opção | Alias | Padrão | Descrição |
|---|---|---|---|
WALLETS_FILE | — | — | Arquivo JSON com lista de carteiras |
--blocks | -b | 100 | Blocos a escanear por carteira |
--json | — | — | Saída como JSON |
--verbose | -v | — | Ativa logs de debug |
Formato do arquivo (lista simples):
["0xWallet1...", "0xWallet2...", "0xWallet3..."]
Formato com rótulos:
[
{"address": "0xWallet1...", "label": "Treasury"},
{"address": "0xWallet2...", "label": "Operations"}
]
arc portfolio report carteiras.json
arc portfolio report carteiras.json --blocks 200 --json
Saída JSON
Todos os comandos que suportam --json retornam dados estruturados para integração com scripts e pipelines:
arc status --json
# {"connected": true, "network": "Arc Mainnet", "chain_id": 5042, "block_number": 21500000, "gas_price_gwei": "0.02"}
arc balance 0xSuaCarteira... --json
# {"address": "0x...", "balance_arc": "1.500000", "nonce": 42}
arc portfolio analyze 0xSuaCarteira... --no-ai --json
# {"address": "0x...", "native_balance": "1.5", "usdc_balance": "10.0", "nonce": 42, "activity_score": "medium", ...}
Ajuda
Qualquer comando aceita --help:
arcdevkit --help
arcdevkit copilot --help
arcdevkit agent --help
arcdevkit debug --help
arc --help
arc send --help
arc portfolio --help
arc debug-batch --help