Appendix C: CLI Commands Reference #

This appendix provides a complete reference for all Neam command-line tools. Neam ships with nine executables, each purpose-built for a specific stage of the development lifecycle.

C.1 neamc -- Compiler and Build System #

The neamc compiler is the primary entry point for building, testing, and deploying Neam projects.

neamc compile #

Compiles a .neam source file (or project) to .neamb bytecode.

neamc compile <source> [options]

# Examples:
neamc compile main.neam -o main.neamb
neamc compile src/main.neam -o build/main.neamb --verbose
neamc compile .   # Compiles project using neam.toml entry point

neamc test #

Discovers and runs test files in the project.

neamc test [options]

# Examples:
neamc test                          # Run all tests in ./tests/
neamc test tests/test_agents.neam   # Run a specific test file
neamc test --filter "billing"       # Run tests matching pattern
neamc test --verbose                # Show detailed test output

Test discovery: neamc test searches for files matching test_*.neam or *_test.neam in the tests/ directory (or the directory specified as an argument). Each test file is compiled and executed. A test passes if it exits without a runtime error. A test fails if it throws an error (including assertion failures from assert_eq, assert_true, etc.).

neamc build #

Compiles the project and all dependencies. Equivalent to neamc compile . but also processes module imports and links standard library modules.

neamc build [options]

# Examples:
neamc build                     # Build project using neam.toml
neamc build --release           # Build with optimizations
neamc build --target windows    # Cross-compile for Windows

neamc deploy #

Generates deployment artifacts for the specified target platform.

neamc deploy <target> [options]

# Examples:
neamc deploy kubernetes --output ./k8s/
neamc deploy aws-lambda --output ./deploy/lambda/
neamc deploy aws-ecs --output ./deploy/ecs/
neamc deploy gcp-cloud-run --output ./deploy/gcp/
neamc deploy azure-container-apps --output ./deploy/azure/
neamc deploy azure-aks --output ./deploy/azure-aks/
neamc deploy docker --output ./deploy/docker/

Supported targets:

Terraform target: When deploying with terraform, the generator produces a complete Terraform module structure:

neamc deploy terraform --output ./terraform/

# Generated structure:
# terraform/
#   main.tf          -- Provider config, ECS/Cloud Run/Container App resources
#   variables.tf     -- Input variables (region, instance count, image tag)
#   outputs.tf       -- Service URL, resource ARNs
#   backend.tf       -- Remote state configuration (S3, GCS, or Azure Blob)
#   modules/
#     networking/     -- VPC, subnets, security groups
#     compute/        -- ECS tasks, Cloud Run services, or AKS deployments
#     monitoring/     -- CloudWatch, Cloud Monitoring, or App Insights

The cloud provider is inferred from the [deploy.*] sections in neam.toml. If multiple cloud sections are present, Terraform generates modules for each.

neamc format #

Formats Neam source files according to the standard style guide.

neamc format [options] [paths...]

# Examples:
neamc format                         # Format all .neam files in the project
neamc format src/main.neam           # Format a specific file
neamc format src/ tests/             # Format specific directories
neamc format --check                 # Check formatting without modifying files

The formatter normalizes indentation (two spaces), brace placement, property alignment in agent and tool declarations, and consistent spacing around operators.

neamc lint #

Runs static analysis checks beyond what the compiler catches.

neamc lint [options] [paths...]

# Examples:
neamc lint                           # Lint all project files
neamc lint src/main.neam             # Lint a specific file
neamc lint --fix                     # Auto-fix lint warnings where possible

Checks performed:

neamc audit #

Runs security and best-practice audits on the project.

neamc audit [options]

# Example output:
# [WARN] Agent "TriageAgent" has no guardrails
# [WARN] Tool "process_refund" has side effects but no confirmation step
# [INFO] 3 agents, 4 tools, 1 knowledge base, 2 guardrails
# [PASS] No circular handoff chains detected
# [PASS] All agent handoff targets exist

Checks performed: - Circular handoff detection - Unreachable agent detection - Missing tool references - Missing knowledge base references - Guardrail coverage analysis - Budget configuration validation - Secret reference validation

neamc add / remove / update #

Manages project dependencies (modules from the package registry).

neamc add <package>[@version]
neamc remove <package>
neamc update [package]

# Examples:
neamc add neam-stdlib@0.5.0
neamc add neam-analytics
neamc remove neam-analytics
neamc update                    # Update all dependencies
neamc update neam-stdlib        # Update a specific package

neamc run-script #

Executes a named script defined in neam.toml.

neamc run-script <name>

# neam.toml:
# [scripts]
# seed = "neam seed_data.neamb"
# migrate = "neam migrate.neamb"

neamc run-script seed
neamc run-script migrate

neamc new #

Creates a new Neam project from a template.

neamc new <project-name> [--template <template>]

# Examples:
neamc new my-agent-project
neamc new customer-service --template multi-agent
neamc new data-pipeline --template autonomous

# Available templates:
#   basic         - Simple agent with one LLM call
#   multi-agent   - Triage + specialist pattern with handoffs
#   rag           - Agent with knowledge base and RAG
#   autonomous    - Scheduled autonomous agent with budget
#   voice         - Agent with voice pipeline
#   full          - All features enabled

neamc generate-ci #

Generates CI/CD pipeline configuration files.

neamc generate-ci <platform> [--output <path>]

# Examples:
neamc generate-ci github-actions --output .github/workflows/
neamc generate-ci gitlab-ci --output .
neamc generate-ci jenkins --output .

# Supported platforms:
#   github-actions  - .github/workflows/neam.yml
#   gitlab-ci       - .gitlab-ci.yml
#   jenkins         - Jenkinsfile

C.2 neam -- VM Runtime #

The neam executable runs compiled bytecode files.

neam <bytecode-file> [options]

# Examples:
neam main.neamb
neam build/customer_service.neamb --config ./neam.toml

C.3 neam-cli -- Interactive Development #

The neam-cli tool provides an interactive REPL, watch mode for hot-reloading during development, and direct program execution.

REPL Mode #

neam-cli
# or
neam-cli --repl

# Interactive session:
# neam> emit "hello";
# hello
# neam> let x = 42;
# neam> emit str(x * 2);
# 84
# neam> agent Bot { provider: "ollama" model: "llama3.2:3b" system: "You are helpful." }
# neam> emit Bot.ask("What is 2+2?");
# 2 + 2 equals 4.
# neam> .exit

Watch Mode #

neam-cli watch <source-file>

# Examples:
neam-cli watch main.neam
neam-cli watch src/main.neam --port 8080

# Watch mode:
# - Compiles and runs the program
# - Monitors the source file (and imports) for changes
# - Automatically recompiles and restarts on save
# - Preserves agent memory across restarts (if memory backend is configured)

Program Execution #

neam-cli run <source-file> [options]

# Examples:
neam-cli run main.neam
neam-cli run main.neam -- --custom-arg value

This compiles the source file in memory and immediately executes it, without producing a .neamb file on disk. Convenient for development and scripting.

C.4 neam-api -- HTTP Server #

The neam-api server exposes Neam agents as REST endpoints and supports the Agent-to-Agent (A2A) protocol.

neam-api [options]

# Examples:
neam-api --port 8080 --agent customer_service.neam
neam-api --port 8080 --agent customer_service.neamb --a2a

REST Endpoints #

A2A Protocol Endpoints (when --a2a is enabled) #

C.5 neam-pkg -- Package Manager #

The neam-pkg tool manages Neam packages (reusable modules of agents, tools, knowledge bases, and guardrails).

neam-pkg init #

Initialize a new package.

neam-pkg init [name]

# Creates:
# neam.toml (with [package] section)
# src/main.neam
# tests/test_main.neam
# README.md

neam-pkg install #

Install a package from the registry.

neam-pkg install <package>[@version]

# Examples:
neam-pkg install neam-analytics
neam-pkg install neam-analytics@1.2.0
neam-pkg install ./local-package  # Install from local directory

neam-pkg update #

Update installed packages.

neam-pkg update [package]

# Examples:
neam-pkg update              # Update all packages
neam-pkg update neam-analytics  # Update a specific package

neam-pkg remove #

Remove an installed package.

neam-pkg remove <package>

neam-pkg search #

Search the package registry.

neam-pkg search <query>

# Example:
neam-pkg search "rag"
# neam-rag-utils     0.3.0  RAG utilities and advanced retrieval strategies
# neam-academic-rag  0.1.0  Academic paper RAG pipeline with citation support

neam-pkg publish #

Publish a package to the registry.

neam-pkg publish [--dry-run]

neam-pkg list #

List installed packages.

neam-pkg list

# Output:
# neam-analytics  1.2.0  installed
# neam-rag-utils  0.3.0  installed

C.6 neam-gym -- Evaluation Framework #

The neam-gym tool provides systematic evaluation of agent performance against labeled datasets.

neam-gym [options]

# Example:
neam-gym \
  --agent customer_service.neam \
  --dataset eval/test_cases.jsonl \
  --output eval/results/ \
  --runs 3 \
  --judge gpt-4o \
  --threshold 0.75

Dataset Format #

Each line in the JSONL dataset is a test case:

{"input": "I want to return my order", "expected_agent": "RefundAgent", "expected_themes": ["return", "refund"]}
{"input": "Why was I charged twice?", "expected_agent": "BillingAgent", "expected_themes": ["billing", "charge"]}

Output Format #

=== neam-gym Evaluation Report ===
Agent: customer_service.neam
Dataset: 10 test cases x 3 runs = 30 evaluations
Judge: gpt-4o
Threshold: 0.75

Results:
  Test  1: 0.89 +/- 0.03  PASS  (routing accuracy)
  Test  2: 0.82 +/- 0.05  PASS  (billing response)
  ...
  Test 10: 0.71 +/- 0.04  FAIL  (edge case)

Overall: 0.81 +/- 0.06 (threshold: 0.75) -> PASS
Passed: 9/10 test cases

C.7 neam-lsp -- Language Server #

The neam-lsp tool implements the Language Server Protocol for IDE integration.

neam-lsp [options]

# Typically started automatically by your editor.
# Manual start (for debugging):
neam-lsp --stdio
neam-lsp --tcp --port 6008

Capabilities #

Editor Setup #

VS Code: Install the "Neam" extension from the marketplace. It automatically starts neam-lsp.

Neovim (with nvim-lspconfig):

require('lspconfig').neam_lsp.setup{
  cmd = { "neam-lsp", "--stdio" },
  filetypes = { "neam" },
  root_dir = require('lspconfig.util').root_pattern("neam.toml"),
}

Emacs (with lsp-mode):

(lsp-register-client
  (make-lsp-client
    :new-connection (lsp-stdio-connection '("neam-lsp" "--stdio"))
    :activation-fn (lsp-activate-on "neam")
    :server-id 'neam-lsp))

C.8 neam-dap -- Debugger #

The neam-dap tool implements the Debug Adapter Protocol for step-through debugging of Neam programs.

neam-dap [options]

# Typically started automatically by your editor's debugger.
neam-dap --port 4711

Capabilities #

VS Code Launch Configuration #

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "neam",
      "request": "launch",
      "name": "Debug Neam Program",
      "program": "${workspaceFolder}/main.neam",
      "stopOnEntry": false,
      "args": []
    }
  ]
}

Debugging Agent Interactions #

The debugger understands agent boundaries. When you step into an agent.ask() call, the debugger shows:

1. The system prompt being sent
2. The message history
3. The tool definitions available to the agent
4. The LLM response (after the call completes)
5. Any tool calls made by the agent
6. Reflection scores (if reflection is enabled)

This makes it possible to debug the entire agent interaction loop step by step, including multi-agent handoffs where control transfers between agents.

C.9 neam-forge -- Forge Agent Runner #

The neam-forge tool runs forge agents from the command line. It compiles and executes a forge agent's iterative build-verify loop, writing progress to stdout and producing structured output files.

neam-forge [options] <source>

# Examples:
neam-forge main.neam
neam-forge main.neam --max-iterations 20 --workspace ./output
neam-forge main.neamb --checkpoint git --verbose

Output Files #

The forge runner produces the following files in the workspace directory:

Exit Codes #

Example Workflow #

# Write a forge agent
cat > builder.neam << 'NEAM'
forge agent Builder {
  provider: "anthropic"
  model: "claude-sonnet-4-20250514"
  system: "You are a Python developer. Build the requested feature with tests."
  max_iterations: 15
  verify: fun(ctx) {
    let result = exec("cd workspace && python -m pytest tests/ -q", 30);
    if (result["exit_code"] == 0) { return true; }
    return f"Tests failed:\n{result['stderr']}";
  }
  checkpoint: "git"
}
NEAM

# Run the forge agent
neam-forge builder.neam --workspace ./my-feature --verbose

# Check the outcome
echo "Exit code: $?"

C.10 Quick Reference #

# Development workflow
neamc new my-project                    # Create project
neam-cli watch src/main.neam            # Develop with hot reload
neamc test                              # Run tests
neamc lint                              # Static analysis
neamc format --check                    # Check formatting
neamc audit                             # Security and best-practice checks

# Build and run
neamc compile main.neam -o main.neamb   # Compile
neam main.neamb                         # Run bytecode
neam-cli run main.neam                  # Compile + run (one step)

# Serve as API
neam-api --port 8080 --agent main.neam  # REST API
neam-api --port 8080 --agent main.neam --a2a  # REST + A2A

# Run forge agents
neam-forge builder.neam                 # Run forge agent
neam-forge builder.neam --verbose       # With detailed output
neam-forge builder.neam --workspace ./out --max-iterations 20

# Deploy
neamc deploy kubernetes --output ./k8s/
neamc deploy aws-ecs --output ./deploy/
neamc deploy terraform --output ./terraform/
neamc deploy docker --output ./deploy/

# Evaluate
neam-gym --agent main.neam --dataset eval.jsonl --runs 3

# Packages
neam-pkg install neam-analytics
neam-pkg search "rag"
neam-pkg publish

# CI/CD
neamc generate-ci github-actions