---
name: teqfw-cli
description: Use this skill when integrating, using, testing, reviewing, or modifying a Node.js TeqFW application that uses @teqfw/cli as its process host, including host Container configuration, CLI command metadata and products, lifecycle plugins, signals, shutdown, or process results.
---

# @teqfw/cli

Use this skill for consumer code that composes or depends on the installed
`@teqfw/cli` package. Treat the host project's instructions, architecture, and
test conventions as authoritative.

## Apply

1. Install `@teqfw/cli` as a host production dependency and invoke its
   published `teq` executable through a package script. npm exposes it as
   `node_modules/.bin/teq` and adds that directory to script `PATH`; use
   `npm exec -- teq help` for an explicit local invocation (`--help` remains
   supported). Do not import
   `@teqfw/cli/src/**`; its runtime modules are DI-addressed.
2. Keep pre-Container composition in the executable. The host owns the one module declared in `teqfw.fw.cli.container.configurator`; packages may publish compatible Configurator contributions for the host to statically import and merge, but must not declare that metadata. Its `container` result is JSON-safe policy data: namespace mappings and Dependency Identifiers for preprocessor, postprocessor, or hardener producers. The CLI supplies standard Sources, and plugins never create or configure a Container. A TeqFW package that declares canonical `teqfw.fw.di.namespaces`, `teqfw.fw.cli.commands`, and a dependency on `@teqfw/cli` may be launched as an explicit host with `teq --host <package> <command> [...]`; see [Usage](references/usage.md) for conventions, the option boundary, and host resolution.
3. Declare commands and optional lifecycle components in the owning package's
   `teqfw.fw.cli` metadata. Discovery reads metadata only; it does not create a
   command product.
4. Treat cfg as mandatory CLI startup infrastructure: the CLI loads the ordered Sources exactly once before resolving lifecycle components. The launcher also initializes the immutable `TeqFw_Cli_Config$` runtime component before that resolution; consume its computed `applicationRoot`, `cwd`, normalized `argv`, and dotenv facts through DI. These facts are separate from user configuration and cannot be overridden by cfg. A lifecycle component implements `TeqFw_Cli_Api_Plugin` with `onStartup()` and `onShutdown()` only. For new components, use the recommended package-owned location and identifier described in [Lifecycle](references/lifecycle.md). Use ordinary declared DI dependencies; never receive the Container, the Bootstrap resolver, or the Host run. See [Usage](references/usage.md) for standard Sources and precedence.
5. A command handler receives `{args, options, signal, launch}`. Finite commands use
   `async execute(context)`; long-running commands use `async start(context)` and
   return `{done, stop}`. See [Usage](references/usage.md) for the fields and
   [Lifecycle](references/lifecycle.md) for signal and shutdown behavior. Let
   only the executable set the process exit code.
6. Read the selected references before editing, then validate with the host
   project's tests.

## Select References

| Consumer task | Read |
| --- | --- |
| Understand boundaries, metadata ownership, or resolution timing | [Concepts](references/concepts.md) |
| Configure the host Container or add a CLI command | [Usage](references/usage.md) |
| Implement lifecycle participation, command lifetime, signals, or cleanup | [Lifecycle](references/lifecycle.md) |
| Mount or discover the installed skill | [Distribution](references/distribution.md) |

`@teqfw/cli` is a Node.js host and lifecycle coordinator. It does not make a
plugin a composition root, expose a general service locator, or let plugins
choose process exit status.