clue

Package Management
  build <?file> ⚑                           Build the current package or a single module
  bump <?pkgOrVersion> <?version> ⚑         Bump the version in the current .nimble file, or a root
                                            dependency's version constraint (`clue bump nim 2.2.0`)
  check <?file> ⚑                           Checks the project for syntax and semantics
  develop                                   Editable install for live library discovery
  dump <?pkg> ⚑                             Dump package info and git activity
  init <?name> ⚑                            Initialize a new nimble project in the current directory
  install <?pkg> ⚑                          Install a package from the registry (or local)
  test ⚑                                    Compile and run test modules in tests/
  update <?pkg> ⚑                           Upgrade a package and its dependencies
  uninstall <pkg> ⚑                         Uninstall a package
  versions <pkg> ⚑                          List available versions
  prune                                     Remove orphaned packages
Directories
  source.add <name> <url> ⚑                 Add a registry source
  source.fetch <?name> ⚑                    Fetch packages.json for a source (or all)
  source.list                               List configured sources
  source.remove <name> ⚑                    Remove a registry source
Environment Management
  venv ⚑                                    Manage virtual environments for Nim projects
Deployment
  deploy.init ⚑                             Scaffold clue.deploy.yaml
  deploy.web ⚑                              Deploy the web target over rsync/ssh (systemd-managed)
Documentation
  docs.gen <pkg> ⚑                          Build documentation for an installed package
  docs.open <pkg> ⚑                         Serve local docs over HTTP (default port 11000)
Code Quality & Maintenance
  doctor                                    Analyze code quality with nimalyzer
  task <?taskName> ⚑                        List or run nimscript tasks from the current .nimble file
  upgrade                                   Self-update clue from GitHub releases

# Build the current package from its nimble file
clue build
clue build --release
clue build --features:ssl,jwt

# Build a single module with all installed packages on the import path
clue build mymodule.nim

# Install / uninstall packages from the registry
clue install spry
clue install spry@1.2.0
clue install ssl#master
clue install https://github.com/user/repo
clue install --build        # build the current dir's package into the registry
clue install spry --build   # install, then compile its binaries to ~/.clue/bin
clue uninstall spry

# Develop mode: link the current package for live library discovery
# (never copies source; uninstalling only removes the entry, never your files)
clue develop

# Inspect the registry
clue dump spry
clue dump spry --refresh    # also re-read versions
clue versions spry --refresh
clue prune

# Create a virtual environment pinned to a specific Nim version
clue venv --nim:2.2.0

source .env/activate     # or: source .env/deactivate

# Build documentation for an installed package (latest version by default)
clue docs.gen spry
clue docs.gen spry@1.2.0

# Serve local docs over HTTP (default port 11000, opens the browser)
clue docs.open spry
clue docs.open spry --port:8080

---
name: nim-clue
description: Use when working on Nim projects (.nim files, .nimble files) — build, test, install packages, and manage the environment with the `clue` package manager instead of nimble or raw `nim c`.
---

# Nim development with clue

## Core rule

In Nim projects, use `clue` as the primary toolchain wrapper. Do NOT use raw
`nim c`, `nimble build`, or `nimble install` unless the user explicitly asks.

Why: clue's depth-first search resolves per-package compiler configuration,
including native C dependencies and header paths (e.g., a package shipping
`spf.h`), which plain `nim c` misses outside the package's own build context.
A build that fails with `fatal error: 'xyz.h' file not found` under `nim c`
usually succeeds under `clue build`.

## Command reference

Full reference (`clue -h`): build 0.2.5. Every flag below mirrors that output.

### Package management
- `clue build <?file:string>` — Build the current package or a single module.
  Default way to compile. Binary lands in project root; redirect with
  `--out:<path>` / `-o:<path>`.
  - `--release:bool` / `--debug:bool` — optimization mode
  - `--features:string` — enable nimble features
  - `--verbose:bool` — verbose output
  - `-b:c|cpp|objc|js` — target backend
  - Example: `clue build src/meowmail.nim --out:bin/meowmail`
- `clue bump <?pkgOrVersion:string> <?version:string>` — Bump version in the
  current `.nimble` file, or a root dependency's constraint
  (`clue bump 1.3.0`, `clue bump nim 2.2.0` with `--level:major|minor|patch`).
- `clue check <?file:string>` — Check project for syntax and semantics
  (`--features:string`).
- `clue develop` — Editable install for live library discovery (symlink under
  `~/.clue/develop`, never copied).
- `clue dump <?pkg:string>` — Dump package info
  (`--refresh:bool` re-reads versions).
- `clue init <?name:string> -Y:bool` — Initialize a new nimble project in the
  current directory (`-Y` non-interactive defaults).
- `clue install <?pkg:string>` — Install from registry or local path/URL
  (`pkg@version`, `pkg#branch`, `https://...`). Flags: `--refresh:bool`,
  `--features:string`, `--verbose:bool`, `--build:bool`, `--debug:bool`,
  `--source:string`, `-b:c|cpp|objc|js`.
- `clue test` — Compile and run test modules in `tests/` (`-b:c|cpp|objc|js`).
- `clue update <?pkg:string>` — Upgrade a package and its dependencies
  (`--verbose:bool`).
- `clue uninstall <pkg:string>` — Remove a package.
- `clue versions <pkg:string>` — List available versions (`--refresh:bool`).
- `clue prune` — Remove orphaned packages.

### Directories (registry sources)
- `clue source.add <name:string> <url:string>` — Add a registry source.
- `clue source.fetch <?name:string>` — Fetch `packages.json` for a source (or all).
- `clue source.list` — List configured sources.
- `clue source.remove <name:string>` — Remove a registry source.

### Environment
- `clue venv --nim:<version>` — Manage virtual environments for Nim projects
  (isolated Nim toolchains per project via choosenim).

### Code quality & maintenance
- `clue doctor` — Analyze code quality with nimalyzer (lint-style checks).
- `clue task <?taskName:string>` — List or run nimscript tasks declared in the
  current `.nimble` file (no arg = list tasks).
- `clue upgrade` — Self-update clue from GitHub releases.

### Documentation
- `clue docs.gen <pkg:string>` — Build documentation for an installed package.
- `clue docs.open <pkg:string>` — Serve local docs over HTTP (default port
  11000, override with `--port:port`).

### Deployment
- `clue deploy.init` — Scaffold `clue.deploy.yaml` (`--type:string`,
  `--workflow:bool`, `--yes:bool`, `--force:bool`).
- `clue deploy.web` — Deploy web target over rsync/ssh (systemd-managed);
  supports `--dry-run:bool`, `--yes:bool`, `--verbose:bool`, `--config:string`,
  `--key:string`, `--profile:string`, `--status:bool`.

## Agent recipes

- Build a binary: `clue build src/<main>.nim` (add `--release` for production)
- Run the test suite: `clue test`
- Add a dependency: `clue install <pkg>` (then `import pkg/<name>` in code)
- Editable dev: `clue develop` then `import pkg/<name>` resolves to working tree
- Registry source: `clue source.add myfork https://.../packages.json` then
  `clue install pkg --source:myfork` or `clue source.fetch`
- Build failure mentioning a missing `.h` file: retry with `clue build` before
  touching include paths manually

### Official repo
When the user asks for more details about Clue (e.g., features, usage, contributing), fetch and read the full README before answering:
https://raw.githubusercontent.com/openpeeps/clue/refs/heads/main/README.md