CLI Reference

Complete reference for Andromeda's command-line interface.

Synopsis

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

Commands

run

Execute JavaScript or TypeScript files.

Syntax:

andromeda run [OPTIONS] <FILES...>

Arguments:

• <FILES...> - One or more files to execute

Options:

• -v, --verbose - Enable verbose output showing detailed execution information
• --no-strict - Disable strict mode (allows more lenient JavaScript parsing)

Examples:

# Run a single file
andromeda run script.ts

# Run multiple files
andromeda run utils.js main.ts helper.ts

# Run with verbose output
andromeda run --verbose my-app.ts

# Run without strict mode
andromeda run --no-strict legacy-script.js

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

Examples:

# Start basic REPL
andromeda repl

# Start REPL with debugging features
andromeda repl --expose-internals --print-internals

# Start REPL with GC disabled (for debugging)
andromeda repl --disable-gc

REPL Commands:

• help - Show available commands
• history - Display command history
• clear - Clear the screen
• gc - Manually trigger garbage collection
• exit or quit - Exit the REPL

compile

Compile a JavaScript/TypeScript file into a single-file executable.

Syntax:

andromeda compile <INPUT> <OUTPUT>

Arguments:

• <INPUT> - Path to the source file to compile
• <OUTPUT> - Path for the output executable

Examples:

# Compile a TypeScript file
andromeda compile my-app.ts my-app.exe

# Compile to a Unix executable
andromeda compile script.js ./my-tool

# Compile with full paths
andromeda compile /path/to/source.ts /usr/local/bin/mytool

fmt

Format JavaScript and TypeScript files.

Syntax:

andromeda fmt [PATHS...]

Arguments:

• [PATHS...] - Files or directories to format (optional, defaults to current directory)

Examples:

# Format specific files
andromeda fmt script.ts utils.js

# Format entire directory
andromeda fmt src/

# Format current directory
andromeda fmt

# Format multiple directories
andromeda fmt src/ tests/ examples/

Supported File Types:

• .js - JavaScript files
• .ts - TypeScript files
• .jsx - JavaScript with JSX
• .tsx - TypeScript with JSX
• .json - JSON files

Global Options

These options are available for all commands:

• -h, --help - Show help information
• -V, --version - Show version information

Examples:

# Show general help
andromeda --help

# Show help for specific command
andromeda run --help

# Show version
andromeda --version

File Types

Andromeda supports these file extensions:

*JSX not actually supported yet

Environment Variables

Andromeda respects these environment variables:

Examples:

# Enable debug logging
RUST_LOG=debug andromeda run script.ts

# Disable colors
NO_COLOR=1 andromeda run script.ts

Debugging

Verbose Output

Use --verbose with the run command to see detailed execution information:

andromeda run --verbose script.ts

This shows:

• File loading times
• Parse times
• Execution times
• Memory usage
• Extension loading

REPL Debugging

Start REPL with debugging options:

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

This provides access to:

• Nova engine internals
• Garbage collection stats
• Detailed execution traces

Error Reporting

Andromeda provides detailed error messages with:

• File location and line numbers
• Syntax highlighting
• Suggestions for fixes
• Stack traces with source context

Examples

Basic Script Execution

# Simple execution
andromeda run hello.ts

# Multiple files with dependencies
andromeda run utils.ts main.ts

andromeda run complex-app.ts

Development Workflow

# Format code
andromeda fmt src/

andromeda run src/main.ts

# Test in REPL
andromeda repl

# Create production executable
andromeda compile src/main.ts dist/my-app

CI/CD Integration

TODO: Write up

completions

Generate shell completion scripts for bash, zsh, fish, or PowerShell.

Syntax:

andromeda completions [SHELL]

Arguments:

• [SHELL] - Target shell (optional, auto-detects if not specified)
  • bash - Bash completion
  • zsh - Zsh completion
  • fish - Fish completion
  • powershell - PowerShell completion

Examples:

# Auto-detect shell and generate completions
andromeda completions

# Generate bash completions
andromeda completions bash > ~/.local/share/bash-completion/completions/andromeda

# Generate zsh completions
andromeda completions zsh > ~/.oh-my-zsh/completions/_andromeda

# Generate fish completions
andromeda completions fish > ~/.config/fish/completions/andromeda.fish

# Generate PowerShell completions
andromeda completions powershell > andromeda.ps1

upgrade

Upgrade Andromeda to the latest version or a specific version.

Syntax:

andromeda upgrade [OPTIONS]

Options:

• -f, --force - Force upgrade even if already on the latest version
• -v, --version <VERSION> - Upgrade to a specific version instead of latest
• --dry-run - Show what would be upgraded without actually upgrading

Examples:

# Upgrade to latest version
andromeda upgrade

# Force reinstall current version
andromeda upgrade --force

# Upgrade to specific version
andromeda upgrade --version v0.2.0

# Check what would be upgraded (dry run)
andromeda upgrade --dry-run

Troubleshooting

For common issues and solutions, see the Troubleshooting Guide.

For more examples check out the Examples