---
title: "Cheatsheet: Comandos CLI do Zig"
url: "https://ziglang.com.br/cheatsheets/cheatsheet-comandos-cli-do-zig/"
markdown_url: "https://ziglang.com.br/cheatsheets/cheatsheet-comandos-cli-do-zig.MD"
description: "Referência rápida para todos os comandos do compilador Zig: build, test, run, fmt, translate-c, fetch e opções de compilação. Guia completo em português."
date: "2026-02-21"
author: "Zig Brasil"
---

# Cheatsheet: Comandos CLI do Zig

Referência rápida para todos os comandos do compilador Zig: build, test, run, fmt, translate-c, fetch e opções de compilação. Guia completo em português.


# Cheatsheet: Comandos CLI do Zig

O compilador Zig é uma ferramenta multifuncional que serve como compilador, linker, test runner, formatador de código e até compilador C/C++. Este guia cobre todos os comandos que você precisa conhecer para trabalhar eficientemente com Zig no terminal.

## Comandos Principais

### zig build — Compilar projeto via build.zig

```bash
# Compilar o projeto (modo debug padrão)
zig build

# Compilar e executar
zig build run

# Executar testes
zig build test

# Compilar com otimização
zig build -Doptimize=ReleaseSafe
zig build -Doptimize=ReleaseFast
zig build -Doptimize=ReleaseSmall

# Cross-compile
zig build -Dtarget=x86_64-linux-gnu
zig build -Dtarget=aarch64-macos-none
zig build -Dtarget=x86_64-windows-msvc

# Passar argumentos para o executável
zig build run -- arg1 arg2 arg3

# Ver todos os steps e opções disponíveis
zig build --help

# Modo verbose — ver comandos executados
zig build --verbose

# Especificar diretório de saída
zig build --prefix ./minha-saida

# Limpar artefatos
zig build --prefix-override ./zig-out && rm -rf zig-out
```

### zig build-exe — Compilar executável diretamente

```bash
# Compilar arquivo único
zig build-exe main.zig

# Com otimização
zig build-exe main.zig -OReleaseFast

# Cross-compile
zig build-exe main.zig -target x86_64-linux-gnu

# Nome de saída customizado
zig build-exe main.zig --name meu-programa

# Linkar com libc
zig build-exe main.zig -lc

# Linkar com biblioteca
zig build-exe main.zig -lSDL2 -lc

# Adicionar caminho de include
zig build-exe main.zig -I/usr/local/include

# Strip de símbolos (binário menor)
zig build-exe main.zig -OReleaseSafe --strip
```

### zig run — Compilar e executar imediatamente

```bash
# Compilar e rodar
zig run main.zig

# Com argumentos
zig run main.zig -- arg1 arg2

# Com otimização
zig run main.zig -OReleaseFast
```

### zig test — Executar testes

```bash
# Rodar todos os testes de um arquivo
zig test arquivo.zig

# Filtrar testes por nome
zig test arquivo.zig --test-filter "somar"

# Modo release
zig test arquivo.zig -OReleaseSafe

# Verbose — ver quais testes executaram
zig test arquivo.zig --verbose

# Com libc
zig test arquivo.zig -lc
```

### zig fmt — Formatar código

```bash
# Formatar arquivo
zig fmt main.zig

# Formatar diretório recursivamente
zig fmt src/

# Verificar formatação sem alterar (CI)
zig fmt --check main.zig
zig fmt --check src/

# Ler de stdin
cat main.zig | zig fmt --stdin
```

## Compilação de Bibliotecas

```bash
# Biblioteca estática
zig build-lib lib.zig

# Biblioteca dinâmica (shared)
zig build-lib lib.zig -dynamic

# Gerar header C
zig build-lib lib.zig -femit-h

# Biblioteca com otimização
zig build-lib lib.zig -OReleaseFast

# Objeto (sem linkar)
zig build-obj modulo.zig
```

## Ferramentas de Tradução e Análise

### zig translate-c — Traduzir C para Zig

```bash
# Traduzir header C para Zig
zig translate-c header.h

# Com defines
zig translate-c -D_GNU_SOURCE header.h

# Com include paths
zig translate-c -I/usr/include header.h

# Salvar saída
zig translate-c header.h > header.zig
```

### zig cc / zig c++ — Compilador C/C++ drop-in

```bash
# Zig como compilador C (drop-in replacement para gcc/clang)
zig cc -o programa main.c
zig cc -O2 -o programa main.c util.c -lm

# Zig como compilador C++
zig c++ -o programa main.cpp -lstdc++

# Cross-compile com zig cc
zig cc -target x86_64-linux-gnu -o programa main.c
zig cc -target aarch64-linux-musl -o programa main.c

# Usar com projetos existentes (substituir CC)
CC="zig cc" make
CC="zig cc" cmake ..
```

## Gerenciamento de Dependências

```bash
# Buscar hash de uma dependência
zig fetch https://github.com/autor/lib/archive/v1.0.tar.gz

# Buscar hash e salvar no cache
zig fetch --save https://github.com/autor/lib/archive/v1.0.tar.gz

# Limpar cache de dependências
rm -rf ~/.cache/zig
```

## Informações e Diagnóstico

```bash
# Versão do compilador
zig version

# Informações do ambiente
zig env

# Listar todos os targets suportados
zig targets

# Listar bibliotecas disponíveis no sistema
zig libc

# Zen do Zig (filosofia)
zig zen
```

## Opções de Compilação

### Tabela de flags comuns

| Flag | Descrição |
|------|-----------|
| `-ODebug` | Sem otimização, com verificações (padrão) |
| `-OReleaseSafe` | Otimizado com verificações de segurança |
| `-OReleaseFast` | Máxima performance |
| `-OReleaseSmall` | Menor binário possível |
| `-target X` | Cross-compile para target X |
| `-lc` | Linkar com libc |
| `-lNOME` | Linkar com biblioteca NOME |
| `-I PATH` | Adicionar caminho de include |
| `-L PATH` | Adicionar caminho de biblioteca |
| `--strip` | Remover símbolos de debug |
| `--name NOME` | Nome do artefato de saída |
| `-femit-h` | Gerar header C |
| `--verbose` | Saída detalhada |

### Targets comuns

```bash
# Linux
zig build -Dtarget=x86_64-linux-gnu
zig build -Dtarget=x86_64-linux-musl    # estático com musl
zig build -Dtarget=aarch64-linux-gnu     # ARM 64-bit

# macOS
zig build -Dtarget=x86_64-macos
zig build -Dtarget=aarch64-macos         # Apple Silicon

# Windows
zig build -Dtarget=x86_64-windows-msvc
zig build -Dtarget=x86_64-windows-gnu    # MinGW

# WebAssembly
zig build -Dtarget=wasm32-freestanding
zig build -Dtarget=wasm32-wasi

# Embedded
zig build -Dtarget=thumb-freestanding     # ARM Cortex-M
zig build -Dtarget=riscv32-freestanding   # RISC-V
```

## Cache e Limpeza

```bash
# Localização do cache global
ls ~/.cache/zig/

# Cache do projeto (local)
ls zig-cache/ 2>/dev/null || ls .zig-cache/ 2>/dev/null

# Limpar cache do projeto
rm -rf zig-cache .zig-cache

# Limpar artefatos de build
rm -rf zig-out
```

## Variáveis de Ambiente

| Variável | Descrição |
|----------|-----------|
| `ZIG_LOCAL_CACHE_DIR` | Diretório do cache local |
| `ZIG_GLOBAL_CACHE_DIR` | Diretório do cache global |
| `ZIG_LIB_DIR` | Diretório da biblioteca padrão |
| `CC` | Compilador C (para `zig cc`) |

## Dicas e Atalhos

```bash
# Compilar e rodar rápido (modo script)
zig run solucao.zig

# Ver AST de um arquivo
zig ast-check arquivo.zig

# Ver assembly gerado
zig build-exe main.zig -femit-asm

# Ver LLVM IR
zig build-exe main.zig -femit-llvm-ir

# Compilação paralela (padrão, usa todos os cores)
# Limitar threads:
zig build -j4  # usar 4 threads
```

## Veja Também

- [Build System](/cheatsheets/build-system/) — Configuração detalhada do build.zig
- [Testing](/cheatsheets/testing/) — Opções do test runner
- [Interop com C](/cheatsheets/c-interop/) — Compilar código C com Zig
- [Instalação do Zig](/instalacao/) — Como instalar Zig
- [Troubleshooting](/troubleshooting/) — Resolver problemas com o compilador