# cli The command line behind `npx hf`, as a function: [`runWorkspaceCli`](https://www.hyperfrontend.dev/docs/libraries/workspace/cli/#api-runWorkspaceCli) takes the arguments, the directory the command ran in and two streams, and resolves to the exit code. ```ts import { runWorkspaceCli } from '@hyperfrontend/workspace/cli' const code = await runWorkspaceCli({ argv: process.argv.slice(2), cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr, }) ``` ## Commands | Command | What it does | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `run : [--name=value ...]` | Runs that one task alone, without the tasks it depends on | | `run-many -t (-p \| --all)` | Runs the tasks and their prerequisites in order, skipping the dependents of a failure | | `affected -t [--base=] [--head=]` | Runs the tasks the change selects, from the merge base with the default branch unless a base is given | | `format --check\|--write [--all \| --files=]` | Runs prettier on the changed files, every file, or the files named | | `generate [--option=value ...]` | Runs a generator of the workspace or of an installed package, by bare name or as `:` | | `show projects [--with-target=] [--json]` | Lists the project names | | `graph ` | Prints, verifies and explains the workspace graph ([`runGraph`](https://www.hyperfrontend.dev/docs/libraries/workspace/cli/#api-runGraph)) | Every command finds the workspace root from any directory below it; generate also runs where no `hf.json` exists yet, taking the working directory as the root. A task's option is given after it as `--name=value`, read as the type the executor's schema declares, or `--name` alone for true; after a shell target the arguments reach the command. The command line's own messages go to standard error, and the exit code is 0 when the command succeeded and 1 otherwise. ## One name, two packages [`@hyperfrontend/features`](https://www.hyperfrontend.dev/docs/libraries/features.md) publishes an executable of the same name for its own commands. With both packages installed, either executable answers every command: a word it does not own is handed to the other package's command line, and `--help` prints both usages. ## API Reference ### Functions #### handOver ```typescript function handOver(invocation: Invocation, host: HandoverHost): Promise ``` Passes a run on to the features command line, when `@hyperfrontend/features` is installed where the command was run. **Parameters** | Name | Type | Description | | --- | --- | --- | | `invocation` | `Invocation` | The run, passed on as it was received | | `host` | `HandoverHost` | How the features command line is found and loaded | **Returns** `Promise`: The exit code of the features command line, or null when the package is not installed **Example: Letting the other command line answer a command this one does not own** ```typescript import { handOver, processHost } from '@hyperfrontend/workspace/cli' const code = await handOver({ argv: ['pack', '.'], cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr }, processHost()) // => the features exit code, or null when @hyperfrontend/features is not installed where the command was run ``` #### isOwnCommand ```typescript function isOwnCommand(word: string): boolean ``` Whether a word is a command this command line owns. **Parameters** | Name | Type | Description | | --- | --- | --- | | `word` | `string` | The first argument | **Returns** `boolean`: True for `run` and every command of the table **Example: Deciding which command line answers** ```typescript isOwnCommand('run-many') // true isOwnCommand('pack') // false: the features command line is asked, when it is installed ``` #### processHost ```typescript function processHost(entry: string): HandoverHost ``` The handover host of the running process: the features command line is resolved from the directory the command was run in, the way Node resolves any installed package. **Parameters** | Name | Type | Description | | --- | --- | --- | | `entry` | `string` | The package entry that holds the command line (default: `FEATURES_CLI`) | **Returns** `HandoverHost`: How this process resolves and loads that entry **Example: Resolving the features command line from where the command was run** ```typescript const host = processHost() host.resolve('/repo/apps/shell') // => '/repo/node_modules/@hyperfrontend/features/cli/index.js', or null when the package is not installed ``` #### runGraph ```typescript function runGraph(argv: unknown, root: string, output: GraphOutput): number ``` Runs the `graph` command. **Parameters** | Name | Type | Description | | --- | --- | --- | | `argv` | `unknown` | The arguments after `graph` | | `root` | `string` | The workspace root, absolute | | `output` | `GraphOutput` | Where the command writes | **Returns** `number`: The exit code: 1 when `verify` finds a difference, 0 otherwise **Example: The tasks a change selects, explained** ```typescript import { runGraph } from '@hyperfrontend/workspace/cli' const output = { say: (line: string) => process.stdout.write(`${line}\n`), note: (line: string) => process.stderr.write(`${line}\n`) } runGraph(['affected', '--target', 'build', '--base', 'origin/main', '--explain'], root, output) // => 0; each selected build and the file that selected it went to `say`, the state build report to `note` ``` **Example: Checking the persisted graph state in CI** ```typescript runGraph(['verify'], root, output) // => 1 when a cold build disagrees with the state on disk ``` #### runWorkspaceCli ```typescript function runWorkspaceCli(options: Invocation, host: HandoverHost): Promise ``` Runs the workspace's command line. The `hf` name is shared with `@hyperfrontend/features`: where that package is installed, a command this one does not own is passed on to its command line, and the usage is followed by its usage. **Parameters** | Name | Type | Description | | --- | --- | --- | | `options` | `Invocation` | The arguments, the starting directory and where to write | | `host` | `HandoverHost` | How the features command line is found and loaded (default: `...`) | **Returns** `Promise`: The exit code: 0 when the command succeeded, 1 otherwise **Example: The command line as a function** ```typescript import { runWorkspaceCli } from '@hyperfrontend/workspace/cli' const code = await runWorkspaceCli({ argv: ['run-many', '-t', 'build', '-p', 'lib-*'], cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr, }) // => 0 when every task succeeded, 1 otherwise ``` **Example: Another `hf` command line passing a command on** ```typescript const code = await runWorkspaceCli({ argv, cwd, stdout, stderr, handedOver: true }) // => the exit code; an unknown command is reported here rather than passed back ``` ### Interfaces #### FeaturesCli The features package's command line, as far as this one calls it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly runFeaturesCli` | `(invocation: Invocation) => Promise` | Runs the features command line and resolves to its exit code. | #### GraphOutput Where the command writes. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly say` | `(line: string) => void` | Writes a line of the result, to standard output. | | `readonly note` | `(line: string) => void` | Writes a line about what the command did on the way, to standard error. | #### HandoverHost How the other command line is found and loaded. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly resolve` | `(cwd: string) => string` | The file of the features command line as a directory resolves it, or null when the package is not installed. | | `readonly load` | `(file: string) => Promise` | Loads the features command line from its file. | #### Invocation One run of a command line, as both packages take it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly argv` | `unknown` | The arguments after the executable's name. | | `readonly cwd` | `string` | The directory the command line was started in. | | `readonly stdout` | `TextSink` | Where results go. | | `readonly stderr` | `TextSink` | Where the command line's own lines go. | | `readonly handedOver?` | `boolean` | Set by the command line that passed this run on, so it is not passed back. | #### TextSink Somewhere text is written. ##### write ```typescript write(text: string): unknown ``` Writes text. **Parameters** | Name | Type | Description | | --- | --- | --- | | `text` | `string` | | ### Types #### WorkspaceCliOptions What a run of the command line is given. ```typescript type WorkspaceCliOptions = Invocation ``` ### Variables #### FEATURES_CLI The entry of the features package that runs its command line. ```typescript const FEATURES_CLI: "@hyperfrontend/features/cli" ``` **Value** `'@hyperfrontend/features/cli'` #### GRAPH_USAGE What the command expects. ```typescript const GRAPH_USAGE: "usage: hf graph projects [--json] | graph [--json] | explain | build [--force] | verify | status [--json] | affected --target [--base ] [--head ] [--json|--explain]" ``` **Value** `'usage: hf graph projects [--json] | graph [--json] | explain | build [--force] | verify | status [--json] | affected --target [--base ] [--head ] [--json|--explain]'` #### USAGE What the command line prints about itself. ```typescript const USAGE: "@hyperfrontend/workspace: run the tasks of a workspace, see what a change affects, and generate code Usage: hf [options] Commands: run : [--name=value ...] Run one task, nothing it depends on first run-many -t [-p | --all] Run tasks and what they depend on affected -t [--base=] [--head=] Run the tasks a change selects format --check|--write [--all | --files=] Run prettier over changed, named or all files generate [...] [--dry-run] Run a generator of the workspace or of an installed package show projects [--with-target=] [--json] List the projects graph Print and explain the workspace graph " ``` **Value** `...` #### WORKSPACE_FILE The file that marks a workspace root. ```typescript const WORKSPACE_FILE: "hf.json" ``` **Value** `'hf.json'` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/cli/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/cli.md Documentation index: https://www.hyperfrontend.dev/llms.txt