The Nostos Command Line

The nostos command is your gateway to running Nostos programs. Whether you're running a simple script, a multi-file project, or using native extensions for high-performance computing, this chapter covers everything you need to know.

Quick Start

The simplest way to run a Nostos program:

# Run a single file
nostos myprogram.nos

# Run a project directory (must contain main.nos)
nostos myproject/

# Start the interactive TUI/REPL
nostos repl

Running Single Files

A Nostos program file needs a main() function as its entry point:

# hello.nos
main() = {
    println("Hello, World!")
    0  # Exit code
}

$ nostos hello.nos
Hello, World!

Running Projects

For larger programs, organize your code into a project directory. By default, the directory must contain a main.nos file (or use [[bin]] entries to specify custom entry points):

myproject/
├── main.nos        # Entry point (or use [[bin]] entries)
├── utils.nos       # Helper functions
├── config.nos      # Configuration
└── nostos.toml     # Project config (optional)

All .nos files in the directory are compiled together, and you can import between them using the module system.

# Run the project
nostos myproject/

Multiple Entry Points

Projects can define multiple executables using [[bin]] sections in nostos.toml. Each entry specifies a name and an entry point in module.function format:

# nostos.toml
[project]
name = "my_app"
version = "0.1.0"

[[bin]]
name = "server"
entry = "server.main"

[[bin]]
name = "cli"
entry = "cli.main"
default = true

With this configuration, your project structure might look like:

myproject/
├── nostos.toml     # Project config with [[bin]] entries
├── server.nos      # Contains server.main()
├── cli.nos         # Contains cli.main()
└── shared.nos      # Shared code used by both

Run different entry points using the --bin flag:

# Run the default entry point (cli.main)
nostos myproject/

# Run a specific entry point
nostos myproject/ --bin server

# Short form
nostos myproject/ -b cli

Using Native Extensions

Extensions let you call high-performance Rust libraries from Nostos. There are two ways to use them:

Method 1: The --use Flag (Recommended)

For standalone scripts, use the --use flag to load an installed extension by name:

# Run a script with the nalgebra linear algebra extension
nostos --use nalgebra myscript.nos

# Use multiple extensions
nostos --use nalgebra --use redis myscript.nos

The extension must be installed in ~/.nostos/extensions/. Example script using nalgebra:

# vector_math.nos
use nalgebra.*

main() = {
    v1 = vec([1.0, 2.0, 3.0])
    v2 = vec([4.0, 5.0, 6.0])

    println("Dot product: " ++ show(vecDot(v1, v2)))
    println("Norm of v1: " ++ show(vecNorm(v1)))
    0
}

$ nostos --use nalgebra vector_math.nos
Loaded extension nalgebra v0.1.0
Dot product: 32.0
Norm of v1: 3.7416573867739413

Method 2: Project Configuration (nostos.toml)

For projects, declare extensions in nostos.toml and they'll be automatically downloaded, built, and loaded:

# nostos.toml
[project]
name = "my-linear-algebra-app"
version = "0.1.0"

[extensions]
nalgebra = { git = "https://github.com/pegesund/nostos-nalgebra" }

Now simply run the project - extensions are handled automatically:

$ nostos myproject/
Found package config: "myproject/nostos.toml"
Loaded extension nalgebra v0.1.0
...

Command Line Options

Here's a complete reference of all available options:

Subcommands

Installing Extensions from GitHub

Native extensions can be installed directly from GitHub repositories using the extension command:

# Install an extension from GitHub
$ nostos extension install https://github.com/pegesund/nostos-nalgebra
Installing extension from https://github.com/pegesund/nostos-nalgebra...
Fetching extension nostos-nalgebra...
Building extension in "/home/user/.nostos/extensions/nostos-nalgebra"...

Extension installed successfully!
  Location: /home/user/.nostos/extensions/nostos-nalgebra
  Library:  /home/user/.nostos/extensions/nostos-nalgebra/target/release/libnostos_nalgebra.so

Use it with:
    nostos --use nalgebra yourprogram.nos

List your installed extensions:

$ nostos extension list
Installed extensions in /home/user/.nostos/extensions:
------------------------------------------------------------
  nostos-nalgebra [built]
      Use with: nostos --use nalgebra <file.nos>

  nostos-glam [built]
      Use with: nostos --use glam <file.nos>

Remove an extension you no longer need:

$ nostos extension remove nalgebra
Removing extension at /home/user/.nostos/extensions/nostos-nalgebra...
Extension 'nalgebra' removed.

Common Examples

# Run a simple script
nostos hello.nos

# Run a project with extensions defined in nostos.toml
nostos myproject/

# Run a standalone script with an extension
nostos --use nalgebra linear_algebra.nos

# Profile a program to find performance bottlenecks
nostos --profile myprogram.nos

# Run with limited threads for testing
nostos --threads 2 concurrent_program.nos

# Debug mode with detailed stack traces
nostos --debug failing_program.nos

# Start the interactive development environment
nostos repl

Interactive REPL

Nostos provides a powerful interactive environment for development and experimentation. You can run the REPL locally or connect to a remote instance.

Local REPL

Start the interactive TUI (Terminal User Interface) with a full-featured editor, file browser, and REPL:

# Start the interactive TUI/REPL
nostos repl

# Or equivalently
nostos tui

# Open the REPL with a specific project directory
nostos repl myproject/

The TUI provides:

• Interactive code evaluation with syntax highlighting
• Built-in code editor with autocomplete
• File browser for project navigation
• Real-time error checking as you type
• Command history and tab completion

Remote REPL

You can also connect to a remote Nostos REPL server. This is useful for debugging production systems or collaborative development.

# Start a REPL server on port 9999
nostos repl --serve 9999

# Connect to a remote REPL server
nostos repl --connect hostname:9999

# Example: connect to localhost
nostos repl --connect localhost:9999

When connected to a remote REPL, you can:

• Inspect variables and state on the remote system
• Evaluate expressions in the remote environment
• Debug running processes
• Hot-reload code changes