Skip to content

Command Line Interface (CLI)

The Harneet interpreter provides a command-line interface (CLI) for running files, starting an interactive session (REPL), and performing other utility tasks. This section details the available flags and their usage.

Flags

--debug (or -d)

  • Type: Boolean
  • Usage: harneet --debug [filename.ha] or harneet -d --repl
  • Description: Enables debug logging, which provides detailed information about the interpreter's internal operations. When this flag is active, a timestamped log file is created in the logs/ directory, capturing each step of the execution process, from lexical analysis to evaluation. This is an invaluable tool for understanding how the interpreter processes your code and for debugging the interpreter itself.

--repl (or -r)

  • Type: Boolean
  • Usage: harneet --repl or harneet -r
  • Description: Starts the Read-Eval-Print Loop (REPL), an interactive mode where you can enter and execute Harneet code line by line. The REPL is perfect for experimenting with the language, testing small code snippets, and getting immediate feedback. To exit the REPL, type exit and press Enter.

--scan

  • Type: String (directory path)
  • Usage: harneet --scan <directory_path>
  • Description: Scans the specified directory recursively and lists and executes all files with the .ha extension. This is a utility feature that helps you quickly find all Harneet source files within a project.

--lint

  • Type: String (file or directory path)
  • Usage: harneet --lint <file_or_directory_path>
  • Description: Lints Harneet files or directories for errors, warnings, and style issues. The linter analyzes your code for syntax errors, style violations, naming convention issues, and other potential problems. It provides detailed feedback with file locations, line numbers, and suggestions for fixes.

--output

  • Type: String (file path)
  • Usage: harneet --lint <target> --output <output_file>
  • Description: Specifies an output file for lint results when using the --lint flag. If not provided, results are displayed in the console. The output file will contain all linting issues in a structured format.

--autoformat

  • Type: Boolean
  • Usage: harneet --lint <target> --autoformat
  • Description: Automatically formats files during linting. When this flag is used with --lint, the linter will not only identify formatting issues but also fix them automatically. This includes correcting indentation, spacing around operators, trailing whitespace, and brace placement.

--config

  • Type: String (TOML file path)
  • Usage: harneet --lint <target> --config <config_file.toml>
  • Description: Specifies a custom TOML configuration file for linting rules. The configuration file allows you to customize which rules are enabled, their severity levels, and various formatting preferences. If not provided, the linter uses default settings.

Environment Variables

In addition to CLI flags, Harneet respects several environment variables that control runtime behaviour. These are optional and primarily useful for benchmarking, debugging, or advanced tuning.

HARNEET_JIT_ENABLED

  • Type: Environment variable (Boolean-like string)
  • Usage: HARNEET_JIT_ENABLED=0 harneet program.ha

  • Description: Controls whether the bytecode JIT compiler is enabled by default.

    • When set to 0 or false (case-insensitive), JIT compilation is disabled for new virtual machines.
    • When set to 1 or true, or when unset, JIT compilation is enabled (default).
    • This is useful for comparing interpreter-only performance against JIT-enabled runs without changing your code.

HARNEET_VM_PERF

  • Type: Environment variable (Boolean-like string)
  • Usage: HARNEET_VM_PERF=1 harneet program.ha

  • Description: Enables collection of detailed VM performance counters (instruction counts, pool/cache hit rates, etc.) even when the CLI --debug flag is not used.

    • When set to 1 or true, new virtual machines will track internal performance counters.
    • When unset (default), performance counters are disabled to keep the hot path as cheap as possible.
    • Note: when you run with --debug, the CLI also enables these counters regardless of this variable so that performance and JIT statistics can be printed.

HARNEET_JIT_TELEMETRY

  • Type: Environment variable (Boolean-like string)
  • Usage: HARNEET_JIT_TELEMETRY=0 harneet program.ha

  • Description: Controls collection of JIT telemetry counters and JIT-specific debug tracing.

    • When set to 0 or false (case-insensitive), JIT statistics (PIC hits/misses, guard failures, trace-shaping counters, etc.) and JIT-only debug traces are disabled while JIT compilation and execution remain enabled.
    • When set to 1 or true, or when unset, JIT telemetry is enabled (default).
    • This is useful when you want maximum JIT performance without the overhead of detailed JIT stats or when you only care about top-level VM performance counters.

Examples

Basic Usage

  • Run a file: 

    1
    harneet program.ha

  • Run a file with debug logging: 

    1
    harneet --debug program.ha

  • Start the REPL: 

    1
    harneet --repl

  • Start the REPL with debug logging: 

    1
    harneet --repl --debug

  • Scan a directory for .ha files and execute the files: 

    1
    harneet --scan ./my_project

Linting Examples

  • Lint a single file: 

    1
    harneet --lint program.ha

  • Lint an entire directory: 

    1
    harneet --lint ./src

  • Lint with output to file: 

    1
    harneet --lint ./src --output lint_results.txt

  • Lint with automatic formatting: 

    1
    harneet --lint program.ha --autoformat

  • Lint with custom configuration: 

    1
    harneet --lint ./src --config my_lint_config.toml

  • Lint with all options combined: 

    1
    harneet --lint ./src --output results.txt --autoformat --config strict.toml

Linting Output

When linting finds issues, the output format includes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
src/main.ha:

  10:5: error: undefined variable 'userName' [undefined-var]
    Suggestion: declare the variable before use

  15:1: warning: variable 'count' should use camelCase naming [variable-naming]
    Suggestion: rename 'user_count' to 'userCount'

  20:25: info: consider using const for this value [prefer-const]

Summary:
  ✗ 1 error(s)
  ⚠ 1 warning(s)
  ℹ 1 info
  Total: 3 issue(s)

Exit Codes

The Harneet CLI uses different exit codes to indicate the result of operations:

  • 0: Success (no issues found or operation completed successfully)
  • 1: Linting found errors or warnings
  • 2: Configuration or validation error
  • 3: Permission error
  • 4: System error (file not found, etc.)
  • 5: Reporting error (failed to write output)

Linting Configuration

The Harneet linter can be customized using TOML configuration files. Here are some example configurations:

Default Configuration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
[rules]
# Core linting rules
gofmt = { enabled = true, severity = "error" }
errcheck = { enabled = true, severity = "error" }
naming-convention = { enabled = true, severity = "warning" }
line-length = { enabled = true, severity = "warning", options = { max-length = 100 } }
indentation = { enabled = true, severity = "error", options = { indent-size = 4 } }

# Style rules
variable-naming = { enabled = true, severity = "warning" }
function-naming = { enabled = true, severity = "warning" }
trailing-whitespace = { enabled = true, severity = "warning" }
comment-format = { enabled = true, severity = "info" }

[formatting]
indent-size = 4
max-line-length = 100
trailing-commas = true
space-around-ops = true
tabs-for-indent = false
no-trailing-space = true

[ignore]
patterns = [
    "*_test.ha",
    "vendor/**",
    "build/**",
    "*.generated.ha"
]

Strict Configuration

For projects that want stricter linting:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
[rules]
# All rules as errors
gofmt = { enabled = true, severity = "error" }
errcheck = { enabled = true, severity = "error" }
naming-convention = { enabled = true, severity = "error" }
line-length = { enabled = true, severity = "error", options = { max-length = 80 } }
variable-naming = { enabled = true, severity = "error" }
function-naming = { enabled = true, severity = "error" }
trailing-whitespace = { enabled = true, severity = "error" }

[formatting]
indent-size = 2
max-line-length = 80
trailing-commas = false
space-around-ops = true
tabs-for-indent = false
no-trailing-space = true

[ignore]
patterns = ["*_test.ha"]

Minimal Configuration

For projects that want only essential linting:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
[rules]
# Only essential rules
gofmt = { enabled = true, severity = "error" }
errcheck = { enabled = true, severity = "error" }
indentation = { enabled = true, severity = "error" }

# Disable style rules
variable-naming = { enabled = false, severity = "warning" }
function-naming = { enabled = false, severity = "warning" }
trailing-whitespace = { enabled = false, severity = "warning" }

[formatting]
indent-size = 4
max-line-length = 120

[ignore]
patterns = [
    "*_test.ha",
    "vendor/**",
    "build/**",
    "examples/**"
]

Available Rules

The Harneet linter supports the following rules:

  • gofmt: Ensures code follows standard formatting
  • errcheck: Checks for proper error handling
  • naming-convention: Enforces naming conventions
  • line-length: Limits line length
  • indentation: Ensures consistent indentation
  • variable-naming: Enforces camelCase for variables
  • function-naming: Enforces camelCase for functions
  • type-naming: Enforces PascalCase for types
  • trailing-whitespace: Detects trailing whitespace
  • comment-format: Ensures proper comment formatting
  • unused-variable: Detects unused variables
  • unused-import: Detects unused imports
  • dead-code: Detects unreachable code

Severity Levels

  • error: Causes linting to fail (exit code 1)
  • warning: Reports issues but doesn't fail linting
  • info: Provides informational messages