# Riot

Riot is an opinionated OCaml stack centered around a single tool, an actor-model runtime, a modern standard library, and the pkgs.ml package registry.

Primary surfaces:
- Landing page: https://riot.ml
- Installer: https://get.riot.ml
- Documentation: https://docs.riot.ml
- Source repository: https://github.com/leostera/riot
- Package registry: https://pkgs.ml

Preferred agent starting points:
- Read the docs for conceptual guidance
- Use pkgs.ml for package discovery and package metadata
- Use api.pkgs.ml for registry publishing, package views, events, and stats

Common commands:
- Install Riot: curl -sSL https://get.riot.ml | sh
- Add a package: riot add <package>
- Publish a package: riot publish
- Update dependencies: riot update
- Run a package or app: riot run <target>

CLI surface:
riot
OCaml build system and package manager

Usage: riot [OPTIONS] [COMMAND]

Options:
  -v, --verbose  Enable verbose output

Commands:
    add            Add a registry, local path, or GitHub dependency and refresh riot.lock
    bench          Run benchmarks with optional substring matching
    build          Build packages
    clean          Clean build artifacts
    completions    Generate shell completions or list completion data
    doc            Generate documentation
    fix            Lint OCaml code and optionally apply safe fixes
    fmt            Format OCaml with krasny
    init           Initialize a new Riot workspace
    install        Install a binary to ~/.riot/bin and project root
    login          Save your pkgs.ml API token
    logout         Remove your saved pkgs.ml API token
    lsp            Start Riot LSP server
    new            Create a new package
    publish        Publish packages to the registry
    rm             Remove a dependency from a manifest section and refresh riot.lock
    run            Run a binary
    search         Search pkgs.ml for packages by name
    snapshots      Review and manage pending snapshot candidates
    test           Run tests with optional substring matching
    toolchain      Manage OCaml toolchains
    update         Re-resolve the workspace graph, update locked package versions, and rewrite riot.lock
    upgrade        Upgrade the globally installed riot binary
    version        Show riot version

See 'riot <command> --help' for more information on a specific command.

What Riot includes:
- a single CLI for toolchain management, package management, formatting, linting, testing, and publishing
- an OCaml actor-model runtime for multicore applications
- a modern standard library for systems programming
- first-party package publishing through pkgs.ml

Related machine-readable docs:
- pkgs registry agent guide: https://pkgs.ml/llms.txt
- pkgs API overview: https://pkgs.ml/api