Referência da CLI

Esta página descreve a CLI implementada na versão 0.2.0-alpha.1. A fonte de verdade é crates/novacli/src/cli.rs; recursos planejados não são apresentados como disponíveis.

Forma geral

nova [--color auto|always|never] <comando> [argumentos]

--help mostra ajuda e --version mostra a versão curta. nova version também lista a versão dos componentes. A opção global --color pode aparecer antes ou depois do comando. NO_COLOR desativa cor quando o modo é auto; FORCE_COLOR solicita cor.

Códigos de saída

Código	Significado
`0`	comando concluído, inclusive `lint` que encontrou apenas avisos
`1`	erro de leitura, compilação, execução, formatação, lint com erro, teste ou pacote
`2`	argumentos inválidos detectados pelo `clap`

Mensagens normais usam stdout. Diagnósticos e a mensagem final de erro usam stderr. A alpha não define códigos distintos para cada classe de falha.

Entradas

Onde <FILE> é aceito, uma extensão omitida é completada com .nova se o arquivo resultante existir.
run, check, tokens, ast, ir e bytecode aceitam um diretório de projeto com nova.toml e usam sua entrada configurada.
build aceita arquivo ou diretório de projeto.
fmt e lint aceitam diretório e procuram .nova recursivamente, ignorando .nova, target, .git e node_modules.
Caminhos com espaços devem ser colocados entre aspas.

Execução e compilação

`nova run`

nova run [--backend vm|interp] [--show-return] [--no-cache] <FILE>

Executa fonte, diretório de projeto ou bytecode .novabc. A VM é o backend padrão. O interpretador é selecionado por --backend interp. --show-return imprime o valor retornado e --no-cache força recompilação de fonte.

nova run .\main.nova
nova run . --backend interp
nova run .\target\app.novabc --show-return

`nova check`

nova check <FILE>

Executa lexer, parser, resolução de módulos, análise semântica e verificação de tipos sem gerar bytecode nem executar o programa.

`nova build`

nova build [-o <OUTPUT>] [--disasm] [--no-cache] <FILE>

Sem -o, imprime o disassembly em stdout. Com -o, grava bytecode binário, exceto quando --disasm é usado ou o nome termina em .txt/.s.

nova build . -o target/app.novabc
nova build main.nova --disasm -o target/app.txt

Inspeção

Comando	Resultado
`nova tokens <FILE> [--meaningful-only]`	tokens; a opção omite newline e EOF
`nova ast <FILE>`	resumo da AST
`nova ir <FILE>`	IR textual
`nova bytecode <FILE>`	disassembly de fonte ou de `.novabc`

Essas saídas são ferramentas de desenvolvimento e ainda não têm formato estável para consumo por scripts.

Projeto

`nova init <NAME>`

Cria um diretório novo com main.nova e nova.toml. O nome aceita letras ASCII, dígitos, _ e -; um diretório existente nunca é sobrescrito.

nova init hello
cd hello
nova run .

Manifesto mínimo

[package]
name = "hello"
version = "0.1.0"
edition = "2021"
entry = "main.nova"

[dependencies]
# math = { path = "../math" }

[build]
output = "target/hello.novabc"

`nova clean [PATH] [--deps]`

Exige nova.toml. Remove target/ e .nova/cache/; --deps também remove .nova/deps/. Esta é uma operação destrutiva e as dependências precisam ser restauradas com nova install.

Qualidade

`nova fmt`

nova fmt [--check] [--indent <N>] <FILES>...

Aceita um ou mais arquivos/diretórios. Por padrão grava as alterações, usa quatro espaços e garante newline final. --check não escreve e retorna 1 se algum arquivo mudaria.

nova fmt .
nova fmt .\src .\tests --indent 2
nova fmt . --check

`nova lint`

nova lint [--deny-warnings] <FILE>

Apesar do nome singular, aceita um arquivo ou diretório. As regras atuais são: variável não usada (L0001), nome fora de snake_case (L0002), ausência de main (L0003), bloco vazio (L0004), TODO/FIXME (L0005), espaço no fim da linha (L0006) e linha acima de 100 caracteres (L0007).

Avisos não falham o comando. --deny-warnings promove os avisos configurados a erros, útil em CI:

nova lint . --deny-warnings

Nesta alpha não existe arquivo público de configuração do formatter/linter.

`nova test`

nova test [PATH] [--backend vm|interp] [--filter <TEXT>]

Procura funções test_* em arquivos *_test.nova. PATH vale . por padrão. O filtro é uma substring do nome. Retorna 1 se qualquer teste falhar; nenhum teste encontrado retorna 0.

Pacotes locais

O gerenciador da alpha é local e experimental.

Comando	Operação
`nova package [PATH] [-o FILE]`	compila e cria `.novapkg`
`nova install [PATH]`	copia dependências por caminho para `.nova/deps` e escreve `nova.lock`
`nova deps [PATH]`	lista dependências do manifesto/lock
`nova publish [PATH]`	publica no registro local `~/.nova/registry`
`nova search [QUERY]`	pesquisa o registro local

Não há download de um registro remoto, verificação criptográfica ou instalador global de pacotes nesta versão.

REPL

nova repl [--no-print-values] [--history <FILE>]

Inicia sessão persistente. --no-print-values conserva apenas stdout; --history define um arquivo de histórico.

LSP

nova lsp [--stdio]

O servidor sempre usa stdin/stdout. --stdio é aceito apenas por compatibilidade. Não execute esse comando esperando um prompt: ele fica aguardando mensagens LSP. O cliente oficial está em editors/vscode.

Ajuda reproduzível

nova --help
nova run --help
nova fmt --help

Para executar a CLI a partir do código-fonte sem instalá-la:

cargo run -p novacli -- --help
cargo run -p novacli -- run examples/hello.nova

Consulte também instalação, VS Code e solução de problemas.