Complete reference for Andromeda's command-line interface (version 0.1.10).

Synopsis

andromeda [COMMAND] [OPTIONS] [ARGS...]

Invoking andromeda with no arguments starts the REPL. Invoking it with a .ts file as the first argument is shorthand for andromeda run.

Commands

run

Execute a JavaScript or TypeScript file.

Syntax:

andromeda run [OPTIONS] <PATH> [-- ARGS...]

Arguments:

• <PATH> — path to the file to execute
• [ARGS...] — additional arguments forwarded to the script (available via Andromeda.args)

Options:

• -v, --verbose — Enable verbose runtime output
• --no-strict — Disable strict mode

Examples:

andromeda run script.ts
andromeda run --verbose my-app.ts
andromeda run --no-strict legacy.js
andromeda run my-app.ts -- --port 3000 --name Alice

repl

Start an interactive Read-Eval-Print Loop.

Syntax:

andromeda repl [OPTIONS]

Options:

• --expose-internals — Expose Nova internal APIs for debugging
• --print-internals — Print internal debugging information
• --disable-gc — Disable garbage collection

Built-in REPL commands: help, history, clear, gc, exit / quit.

andromeda repl
andromeda repl --expose-internals --print-internals
andromeda repl --disable-gc

compile

Compile a script into a single-file executable.

Syntax:

andromeda compile [OPTIONS] <PATH> <OUT>

Options:

• -v, --verbose — Embed verbose mode in the binary
• -s, --no-strict — Disable strict mode in the binary

Examples:

andromeda compile my-app.ts my-app
andromeda compile -v src/main.ts dist/tool

The resulting executable embeds your script plus the configuration block, so it can run on any matching platform without andromeda installed.

bundle

Bundle a JavaScript/TypeScript entry file and its dependencies into a single minified output file.

Syntax:

andromeda bundle <INPUT> <OUTPUT>

Examples:

andromeda bundle src/main.ts dist/app.js

fmt

Format JavaScript, TypeScript, and JSON files using the built-in formatter (dprint).

Syntax:

andromeda fmt [PATHS...]

If no paths are provided, formats the current directory. File discovery respects format.include and format.exclude from your config.

Examples:

andromeda fmt
andromeda fmt src/ tests/
andromeda fmt script.ts utils.js

Supported file types: .js, .ts, .jsx, .tsx, .mjs, .mts, .json.

lint

Run the built-in linter against your code.

Syntax:

andromeda lint [PATHS...]

Built-in rules:

• Empty function detection
• Empty statement detection
• Variable usage validation
• Unreachable code detection
• Invalid syntax highlighting

The set of enabled and disabled rules can be customised through the lint section of andromeda.json.

Examples:

andromeda lint
andromeda lint src/ tests/
andromeda lint script.ts utils.js

check

Type-check TypeScript files.

Syntax:

andromeda check [OPTIONS] [PATHS...]

Options:

• --json — Emit one JSON object per diagnostic (ndjson) on stdout. Progress and summary lines still go to stderr. Conflicts with --quiet.
• --quiet — Suppress all output and rely on the exit code. Conflicts with --json.

Examples:

andromeda check
andromeda check src/
andromeda check --json src/ | jq .
andromeda check --quiet && echo ok || echo "type errors"

lsp

Start the Language Server Protocol server. This is typically invoked by your editor rather than directly.

Syntax:

andromeda lsp

Features:

• Real-time diagnostics
• Built-in linting rules (matching andromeda lint)
• Multi-file workspace analysis
• Editor integration (VS Code, Neovim, and other LSP clients)

task

Run tasks defined in andromeda.json (or .toml / .yaml). Tasks are inspired by Deno's task system.

Syntax:

andromeda task [TASK_NAME]

If TASK_NAME is omitted, all available tasks are listed.

Defining tasks: add a tasks map to your config. A task can be a string or a richer object with description, dependencies, working directory, and environment overrides.

{
  "tasks": {
    "dev": "andromeda run src/main.ts",
    "test": "andromeda run tests/main.ts",
    "build": {
      "description": "Bundle and compile",
      "command": "andromeda bundle src/main.ts dist/app.js",
      "dependencies": ["test"],
      "env": { "NODE_ENV": "production" }
    }
  }
}

Examples:

andromeda task           # list tasks
andromeda task dev
andromeda task build

config

Manage Andromeda configuration files.

Syntax:

andromeda config <SUBCOMMAND>

config init

Create a new configuration file with defaults.

andromeda config init                       # andromeda.json
andromeda config init --format toml
andromeda config init --output ./conf/andromeda.json
andromeda config init --force               # overwrite existing

Options:

• --format <json|toml|yaml> — default json
• -o, --output <PATH> — output location
• -f, --force — overwrite an existing file

config show

Print the resolved configuration. Reads andromeda.json / andromeda.toml / andromeda.yaml from the current or parent directories.

andromeda config show
andromeda config show --file ./custom.toml

config validate

Validate a configuration file.

andromeda config validate
andromeda config validate --file ./andromeda.json

For full configuration reference, see the Configuration Guide.

completions

Generate shell completion scripts.

Syntax:

andromeda completions [SHELL]

If no shell is provided, Andromeda auto-detects from $SHELL (or PowerShell on Windows). Supported shells: bash, zsh, fish, powershell.

andromeda completions
andromeda completions bash > ~/.local/share/bash-completion/completions/andromeda
andromeda completions zsh > ~/.zfunc/_andromeda
andromeda completions fish > ~/.config/fish/completions/andromeda.fish
andromeda completions powershell > andromeda.ps1

upgrade

Upgrade Andromeda to the latest version (or a specific version).

Syntax:

andromeda upgrade [OPTIONS]

Options:

• -f, --force — Re-install even if already on the latest version
• -v, --version <VERSION> — Upgrade to a specific version
• --dry-run — Show what would change without applying

andromeda upgrade
andromeda upgrade --dry-run
andromeda upgrade --force
andromeda upgrade --version 0.1.10

Global Options

• -h, --help — Show help (works on each subcommand too)
• -V, --version — Show the Andromeda version

andromeda --help
andromeda run --help
andromeda --version

File Types

Andromeda treats these extensions as runnable / formattable:

*JSX syntax is parsed by the formatter and linter but is not yet executed at runtime.

Environment Variables

RUST_LOG=debug andromeda run script.ts
NO_COLOR=1 andromeda run script.ts

Debugging

Verbose Output

andromeda run --verbose script.ts

Shows extension loading, parse and execution timing, and other diagnostics.

REPL Internals

andromeda repl --expose-internals --print-internals

This exposes Nova engine internals — primarily useful when working on the runtime itself.

Error Reporting

Andromeda surfaces source-mapped errors with file location, syntax highlighting, and stack traces with context.

Examples

Basic Script Execution

andromeda run hello.ts
andromeda run --verbose app.ts

Development Workflow

andromeda fmt src/
andromeda lint src/
andromeda check src/
andromeda run src/main.ts

Production Workflow

andromeda check && andromeda lint
andromeda bundle src/main.ts dist/app.js
andromeda compile src/main.ts dist/my-app

Single-File Executable

andromeda compile src/cli.ts ./tool
./tool --help

Troubleshooting

For common issues and solutions, see the Troubleshooting Guide.

For more code samples, browse the Examples.