context7.json

{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "@imqueue/cli",
  "description": "Command line interface for @imqueue — scaffold Redis-RPC microservices, generate typed clients, and manage a local service fleet.",
  "branch": "master",
  "excludeFolders": ["src", "lib", "bin", "test", "tests", "dist", "coverage", "node_modules", "scripts", ".github"],
  "excludeFiles": ["CHANGELOG.md", "LICENSE", "CLAUDE.md", "CONTRIBUTING.md", "CONTRIBUTION-TERMS.md", "SECURITY.md", "wiki/_Sidebar.md", "wiki/README.md"],
  "rules": [
    "@imqueue/cli is the `imq` command for the @imqueue framework: it scaffolds Redis-RPC services from templates, generates typed clients, and runs a local fleet. Install globally with `npm i -g @imqueue/cli`.",
    "The command surface is `imq service`, `imq client`, `imq config`, `imq ctl`, `imq log`, `imq up` and `imq completions`. Run bare `imq` for the summary.",
    "From 4.x the standalone `imqctl`, `imqlog` and `imqup` tools are subcommands — `imq ctl`, `imq log`, `imq up` — with unchanged options. Do not suggest the old binaries.",
    "Scaffold with `imq service create <name> <path>`, e.g. `imq service create billing ./billing`.",
    "`imq client generate <name> [path]` needs the service RUNNING and Redis reachable, because it introspects the live interface. Against a stopped service it waits, then fails.",
    "The name `imq client generate` takes is the service's QUEUE name, which IMQService defaults to its own class name (`this.name = name || this.constructor.name`); the CLI passes it straight to IMQClient.create().",
    "So it is `imq client generate BillingService ./src/clients`, not `billing`. The lower-case project or directory name is what `imq ctl -s` takes — the two are different names and mixing them up times the generator out.",
    "Generation writes `<path>/<Name>.ts`, whose only export is a namespace named after the service with a lower-case first letter, holding a class whose trailing `Service` is replaced by `Client`.",
    "`-o, --overwrite` replaces an existing client without prompting; `-w, --timeout` is seconds to wait for the service (default 30, and `0` waits forever).",
    "Development flow: `imq ctl start -s billing -c` to bring it up and wait for readiness, then `imq client generate BillingService ./src/clients`, then `imq ctl stop -s billing`.",
    "`imq service update-version <path> [branch]` releases across one or many services: git checkout, pull, `npm version`, `git push --follow-tags`, stopping that service at the first failing step.",
    "update-version detects services by LOADING the built module and walking the prototype chain for IMQService, so the class need not be named `*Service`. `imq up` and `imq ctl` detect by scanning source instead.",
    "Use `imq service update-version` for a release against built, committed services, and `imq up` for dependency maintenance (`ncu -u` plus reinstall). update-version takes `-b/[branch]`, default master; `imq up` uses the current branch.",
    "Every option resolves by a strict precedence: flag, then the per-service `.imqrc.json`, then global config, then an interactive prompt, then the default. So CI and scripted runs never hang waiting for input.",
    "`imq config init | get | set | check` manages settings. The CLI home is `~/.imq/`, and IMQ_CLI_HOME relocates it — which is how you give each project an isolated CLI environment.",
    "`imq service create --packages <list>` adds addon packages; `--no-packages` means explicitly none; `imq config set packages opentelemetry,pg-cache` sets a default for every new service.",
    "List every addon id with `imq service packages`, or `imq service packages --json` for a machine-readable form.",
    "Two addon groups are EXCLUSIVE and accept at most one member: tracing/APM (`opentelemetry`, `dd-trace`) and ORM/database (`pg-prisma`, `sequelize`). Selecting two members of one group is rejected with an error.",
    "At most one, not exactly one: selecting no ORM is a normal answer and the right one for a service that talks to no database.",
    "Catalog ids are not npm names, and two no longer match: `dd-trace` installs @imqueue/datadog and `sequelize` installs @imqueue/pg-sequelize. The ids stayed put through the renames so existing configs keep working.",
    "The non-exclusive feature group is pg-cache, pg-pubsub, tag-cache, job, net, http-protect, graphql-dependency, type-graphql-dependency, validation, core and gcp.",
    "The `core` addon adds @imqueue/core as a direct dependency. It already arrives transitively through @imqueue/rpc, so take it only when the service imports from it directly.",
    "The `gcp` addon is the Google Cloud Trace exporter: it needs `opentelemetry` selected as well, and exports once GOOGLE_APPLICATION_CREDENTIALS is set.",
    "Defaults are `pg-prisma` for the ORM and `opentelemetry` for tracing — unless the surrounding fleet already agrees on something else, in which case matching the fleet wins.",
    "`imq service create` treats sibling directories whose package.json depends on @imqueue/rpc as the fleet, and preselects the ORM and tracing members they agree on. A strict majority wins; a tie preselects nothing.",
    "The fleet scan is cached in `~/.imq/var/fleet.json`, keyed by directory and invalidated when the set of sibling directories changes. Choosing against the analysis is recorded as an override for that directory.",
    "For each selected addon the scaffolder merges its dependencies, injects code at the `%ADDON_PRELOAD` and `%ADDON_CONFIG` template tokens, may add files, and prints the environment variables that addon needs.",
    "A traced service's reported name comes from SERVICE_NAME via `src/config.ts` on v2 templates (zod-validated, defaulting to the scaffolded name), or from an inlined IMQ_SERVICE_NAME on v1. `dd-trace` takes neither — use DD_SERVICE.",
    "Do not confuse those with the `%SERVICE_NAME` template token, which is substituted once at scaffold time and is not read at runtime.",
    "Templates and the addon catalog live in a separate repo, pointed at by IMQ_TEMPLATES_REPO and `templatesRef`, so new addons can appear without a CLI release.",
    "Every network endpoint has an environment-variable override, which is what makes GitHub Enterprise, self-managed GitLab and Bitbucket-compatible endpoints work.",
    "On every interactive run `imq` checks npm for a newer release and offers to self-update. Set IMQ_NO_UPDATE_CHECK=1 to skip that check in scripts and CI.",
    "`imq completions` installs or removes shell completions for bash and zsh.",
    "Requires Node.js 22.12+. The package is ESM-only. Shell snippets assume a POSIX shell, so Windows users should use WSL or Git Bash.",
    "@imqueue/cli is GPL-3.0-only. Commercial licensing for closed-source products: https://imqueue.com/license/.",
    "The full CLI manual is at https://imqueue.org/cli/; a machine-readable docs index at https://imqueue.org/llms.txt; a hosted MCP server for agents at https://mcp.imqueue.org/mcp."
  ],
  "url": "https://context7.com/imqueue/cli",
  "public_key": "pk_fjNtG1ue4XLAYwKYgyOMq"
}