CLI para dados do mercado financeiro brasileiro. Ações, índices, macro (CDI/SELIC/IPCA), DI1, COTAHIST, notícias da B3 — direto do terminal.
$ finbr macro cdi
0.144
$ finbr acao PETR4
PETR4 — resumo
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ campo ┃ valor ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ nome │ PETROBRAS PN │
│ preco │ 38.42 │
│ valor_de_mercado │ 501,000,000,000 │
│ ... │ ... │
└──────────────────────┴───────────────────────────────────────────┘Recomendado (instala finbr no PATH globalmente, isolado em venv próprio):
uv tool install git+https://github.com/renanmoretto/finbrSem instalar (execução efêmera):
uvx --from git+https://github.com/renanmoretto/finbr finbr macro cdiPip clássico:
pip install git+https://github.com/renanmoretto/finbrfinbr acao <ticker> [verbo] — info, multiplos, dividendos, resultados, balanco, fluxo, precos, ...
finbr indice <nome> [verbo] — precos, composicao
finbr macro <verbo> — cdi, selic, ipca, acumulado, corrigir, serie, buscar, info
finbr di1 <ticker> <verbo> — vencimento, dias, taxa, pu, dv01
finbr b3 cotahist <dia|ano> — arquivos COTAHIST da B3
finbr b3 noticias — plantão de notícias
finbr dus <verbo> — calendário de dias úteis (B3)
finbr cache <verbo> — info, limpar (cache em disco)
finbr screener — screener de ações
finbr comparar <tickers...> — indicadores de várias ações lado a lado
Todo comando aceita --help. Por exemplo: finbr acao --help, finbr macro ipca --help.
Por padrão, a CLI imprime tabela colorida quando rodando interativamente, e CSV quando a saída é piped/redirecionada — ou seja, "faz a coisa certa" automaticamente.
finbr macro buscar cdi # tabela bonita no terminal
finbr macro buscar cdi | head # CSV, pronto pra pipe
finbr macro buscar cdi -f json | jq . # JSON para jq
finbr macro ipca -o ipca.csv # salva CSV
finbr b3 cotahist ano 2024 -o 2024.parquet # salva ParquetFlags universais:
-f, --format {auto,table,json,csv,parquet}— formato explícito.-o, --output FILE— salva em arquivo (formato inferido da extensão).
Onde for aceitar uma data, vale:
2024-01-15 # ISO
2024-01 # primeiro dia do mês
today, hoje
yesterday, ontem
-5d -2w -3m -1y
Exemplos:
finbr acao PETR4 precos --since -1y
finbr b3 cotahist dia ontem
finbr macro ipca --since 2020-01-01
finbr dus delta today -n -5Downloads de COTAHIST e séries do SGS ficam em cache em disco, então repetir um comando é instantâneo.
finbr cache info # onde está e quanto ocupa
finbr cache limpar # apaga tudo
FINBR_NO_CACHE=1 finbr macro cdi # ignora o cache nesta chamada- Diretório:
~/.cache/finbr(ou$XDG_CACHE_HOME/finbr;FINBR_CACHE_DIRsobrescreve). - Validade: SGS 1h; COTAHIST de pregões e anos encerrados não expira; ano corrente 6h, dia corrente 1h.
- Vale também para o uso como biblioteca (
sgs.get,cotahist.get,cotahist.get_ano).
finbr acao PETR4 # resumo rápido (preço, MV, segmento, etc.)
finbr acao PETR4 multiplos # múltiplos históricos
finbr acao PETR4 dividendos # histórico de dividendos
finbr acao PETR4 dividendos --fonte fundamentus
finbr acao PETR4 resultados --periodo anual --ano-inicio 2018
finbr acao PETR4 balanco # balanço patrimonial
finbr acao PETR4 fluxo # fluxo de caixa
finbr acao PETR4 precos --since -1y # preços do último ano (Yahoo)
finbr acao PETR4,VALE3,ITUB4 precos # fechamento de vários tickers, um por coluna
finbr acao PETR4,VALE3 precos --campo volume
finbr comparar PETR4 VALE3 ITUB4 # indicadores lado a lado
finbr comparar PETR4 VALE3 -c p_l,p_vp,dy,roeVários tickers vão separados por vírgula em finbr acao (o token seguinte é o verbo) e por espaço em finbr comparar.
finbr indice IBOV # composição atual
finbr indice IBOV precos # série histórica completa
finbr indice SMLL precos --ano-inicio 2015 --ano-fim 2023finbr macro cdi # CDI ao ano
finbr macro cdi --diario # CDI diário
finbr macro selic
finbr macro ipca --since -5y # IPCA mensal dos últimos 5 anos
finbr macro serie 12 --since 2024-01-01 # série SGS arbitrária
finbr macro buscar inflacao # buscar séries SGS
finbr macro info 433 # metadados da sérieAcumulado e correção de valores (ipca, igpm, inpc, cdi, selic):
finbr macro acumulado ipca # IPCA acumulado em 12 meses
finbr macro acumulado cdi --de 2023-01-01 --ate 2024-01-01
finbr macro corrigir 1000 --de 2020-01 # R$ 1000 de jan/2020 corrigidos pelo IPCA até hoje
finbr macro corrigir 1000 --de 2020-01 --ate 2023-12 --indice igpmÍndices mensais contam do mês de --de ao mês de --ate, ambos inclusive; os diários (CDI, SELIC) vão de --de (inclusive) a --ate (exclusive) — a mesma convenção da Calculadora do Cidadão do Banco Central. A saída mostra o período efetivamente usado.
finbr di1 DI1F26 # default: data de vencimento
finbr di1 DI1F26 vencimento # data de vencimento
finbr di1 DI1F26 dias # dias úteis até o vencimento
finbr di1 DI1F26 pu 0.12 # preço unitário dado taxa
finbr di1 DI1F26 taxa 95000 # taxa dado PU
finbr di1 DI1F26 dv01 0.12 # DV01finbr b3 cotahist dia 2024-10-15 # cotações de um pregão
finbr b3 cotahist ano 2024 -o 2024.parquet
finbr b3 noticias # plantão de hoje
finbr b3 noticias --since -7d --ticker PETR4finbr dus proximo # próximo dia útil
finbr dus ultimo # dia útil anterior
finbr dus delta today -n -5 # 5 dias úteis atrás
finbr dus dif 2024-01-01 2024-06-01 # nº de dias úteis entre datas
finbr dus eh-util 2024-12-25 # "não"
finbr dus feriados 2024 # feriados do anofinbr screener --limit 20 # 20 primeiras linhas
finbr screener -o screener.csv # exporta tudo
finbr screener --where "p_l > 0 and p_l < 10 and dy > 6" --sort dy --desc
finbr screener -w "roe > 15" -w 'sectorname == "Financeiro e Outros"' -c ticker,price,p_l,roe-w, --where EXPR— filtro sobre as colunas; pode repetir (combinados com AND).-s, --sort COL/--desc— ordenação.-c, --colunas A,B,C— colunas exibidas.
Percentuais vêm em pontos (dy > 6 = 6%). Principais colunas: ticker, price, p_l, p_vp, dy, roe, roic, margemliquida, dividaliquidaebit, liquidezmediadiaria, valormercado, sectorname.
finbr também funciona como biblioteca — os mesmos dados em Python:
import finbr
finbr.cdi() # 0.144
finbr.selic()
finbr.ipca() # pd.DataFrame
from finbr import sgs, dias_uteis
from finbr.b3 import di1, indices, cotahist, plantao_noticias
from finbr.statusinvest import acao
from finbr import fundamentus
sgs.get(12, data_inicio='2024-01-01')
finbr.correcao.acumulado('ipca') # IPCA 12 meses
finbr.correcao.corrigir(1000, 'ipca', '2020-01-01')
indices.preco_historico('IBOV', ano_inicio=2020)
acao.detalhes('PETR4')
di1.taxa('DI1F26', preco_unitario=95000)
dias_uteis.proximo()Tudo o que a CLI faz está disponível como função Python — a CLI é só um wrapper fino sobre os módulos. Os módulos exportados são os mesmos da v0.2.x, sem mudanças que quebrem código existente.
MIT