# @pecometer/peco-cli

> Pecometer Command Line Interface Application with monorepo support

Latest version **3.1.1** (published 2026-09-24) · SEE LICENSE IN licence license · 0 weekly downloads

## Install

```sh
npm install @pecometer/peco-cli
pnpm add @pecometer/peco-cli
yarn add @pecometer/peco-cli
bun add @pecometer/peco-cli
```

Provides the command `peco-cli`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.1.1 |
| Published | 2026-09-24 |
| First published | 2019-06-26 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN licence |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 8 |
| Unpacked size | 119.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Sean Hutchinson |
| Maintainers | seanhutchinson |
| Keywords | Pecometer, Command, Line, App, Monorepo |

## Links

- npm: https://www.npmjs.com/package/@pecometer/peco-cli
- Repository: https://bitbucket.pecometer.co.uk:7999/pec/peco-cli
- npm.io page: https://npm.io/package/@pecometer/peco-cli

## Dependencies (8)

- [yaml](https://npm.io/package/yaml.md) 2.9.1
- [dotenv](https://npm.io/package/dotenv.md) ^17.4.2
- [lodash](https://npm.io/package/lodash.md) ^4.18.1
- [semver](https://npm.io/package/semver.md) ^7.8.5
- [@swc/core](https://npm.io/package/@swc/core.md) ^1.15.41
- [@swc/helpers](https://npm.io/package/@swc/helpers.md) ^0.5.23
- [package-json](https://npm.io/package/package-json.md) ^10.0.1
- [@swc-node/register](https://npm.io/package/@swc-node/register.md) ^1.11.1

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 3.1.1 (latest) — 2026-09-24
- 3.1.0 — 2026-09-23
- 3.0.0 — 2026-06-22
- 2.0.0 — 2025-12-10
- 1.10.0 — 2023-01-07
- 1.9.2 — 2022-02-28
- 1.9.1 — 2022-02-04
- 1.9.0 — 2021-12-30
- 1.8.0 — 2021-06-10
- 1.7.0 — 2021-01-12
- 1.6.0 — 2020-09-21
- 1.5.0 — 2020-03-20
- 1.4.0 — 2020-02-14
- 1.3.3 — 2020-01-08
- 1.3.2 — 2019-12-02
- … 11 more at https://npm.io/package/@pecometer/peco-cli/versions

## README

# PecoCLI

A command line app that is primarily used to setup a Node.js project with [PecoTS](https://www.pecots.co.uk) (backend) and Angular (frontend) as the main frameworks.
[PecoTS](https://www.pecots.co.uk) is a closed source framework, and this tool has very little use outside of working with the framework.

## Create A New App

Use this command to quickly prepare an application directory with a backend, frontend, or both basic applications.
The process will ask for various details depending on the options selected.

```
peco-cli create-app
```

## Generate DOTENV

Generate a .env file for your PecoTS application using the `generate-env` command. The file will be created in the current directory.

```
peco-cli generate-env
```

## Check Update

Checks if an update to the CLI package is available.

```
peco-cli check-update
```

## Version

Outputs the current package version to the console.

```
peco-cli version
```

## Dev Console

Local development often runs several long-running processes at once (for example a
PecoTS backend, an agent and a Webpack frontend) via `concurrently`. Their combined
output is noisy and a crash in one usually means stopping and restarting everything.

The `dev` command replaces that workflow with a declarative `peco-cli.yml` config and a
condensed status view. It is only available when a `peco-cli.yml` file is present in the
current directory.

### Running

```
# Run the default profile (or pick interactively when no default is defined)
peco-cli dev

# Run every declared process
peco-cli dev all

# Run a named profile
peco-cli dev services

# Run specific processes (space- or pipe-separated)
peco-cli dev backend frontend
peco-cli dev backend|frontend
```

Running the bare `peco-cli` command in a directory that contains a `peco-cli.yml` offers
`dev` as a numbered picker option before falling back to the built-in command list.

### The `peco-cli.yml` format

```yaml
processes:
    backend:
        command: node --watch --no-warnings --import @swc-node/register/esm-register ./server.ts
        cwd: backend
        env:
            NODE_ENV: development
    agent:
        command: node --watch --no-warnings --import @swc-node/register/esm-register ./server.ts
        cwd: agent
    frontend:
        command: node ../node_modules/.bin/webpack serve --config config/webpack.dev.cjs
        cwd: frontend
profiles:
    default: [backend, frontend]
    services: [backend, agent]
```

- **processes** — a non-empty map of named processes. Each process has:
    - `command` — a whitespace-separated string (tokenised into an argv array) or an
      explicit argv array such as `["node", "./server.ts"]`. Commands are executed
      directly, never through a shell.
    - `cwd` — optional working directory, resolved relative to the project root.
    - `env` — optional map of extra environment variables merged over the current
      environment.
    - `ready` — optional regular-expression string; when a line matches it the process
      is marked as running.
- **profiles** — optional named lists of process keys. `default` is used automatically
  when `peco-cli dev` is run with no selection. The name `all` is reserved and always
  expands to every declared process.

### Selection precedence

1. No tokens → the `default` profile if defined, otherwise an interactive multi-select.
2. `all` (case-insensitive) → every declared process in declaration order.
3. A single token matching a profile name → that profile's processes.
4. Otherwise every token is treated as a process key; an unknown key lists the available
   processes and profiles and starts nothing.

### The status view

On an interactive terminal, `dev` takes over the screen with a full-screen status view that
redraws in place — no endless scrolling. It has a two-line header, a Processes pane, a live
Output pane and a footer of key hints:

```
┌──────────────── PecoTS CLI © 2026 Pecometer Software Limited ────────────────┐
│                              @acme/api-server                                │
├──────────── Processes ────────────┬─────────────── Output ───────────────────┤
│ ▶ backend                 RUNNING │ [backend] Completed running './server'    │
│   frontend                RUNNING │ [backend] heartbeat 14                    │
│   flaky          CRASHED (code 1) │ [backend] heartbeat 15                    │
│                                   │ ...                                       │
├────────────────────────────────────┼───────────────────────────────────────────┤
│ [↑/↓] select  [r] restart  [q] quit │ [PgUp/PgDn] scroll  [Home/End] first/last │
└────────────────────────────────────┴───────────────────────────────────────────┘
```

- **Header** — line one is a static CLI banner (only the year changes); line two shows the
  running project's `package.json` name for visibility, and is blank when there is none.
- **Processes pane** — one line per process showing its key and a coloured status: `RUNNING`
  (green), `STARTING`/`RESTARTING` (yellow), `ERROR`/`CRASHED` (red), `STOPPED` (cyan). A
  crash shows the exit reason inline, for example `CRASHED (code 1)` or
  `CRASHED (signal SIGKILL)`. The selected process is marked with `▶`.
- **Output pane** — a live-tailing log for the selected process, newest lines at the bottom.
  It is shown when the terminal is wide enough (roughly 80+ columns) and is capped at half
  the terminal width; on narrower terminals the view collapses to the Processes list only.

Keys:

- `↑` / `↓` — move the selection between processes; the Output pane follows the selection.
- `r` — restart the selected process without touching the others. Useful for resetting a
  crashed watcher without stopping the rest.
- `PgUp` / `PgDn` — scroll the selected process's log, back through the most recent five
  pages; scrolling back to the bottom resumes the live tail.
- `Home` / `End` — jump to the oldest retained log line, or back to the live tail.
- `q` or `Ctrl-C` — stop every process (SIGTERM escalating to SIGKILL) and quit with no
  orphaned processes. The terminal is always restored to its previous state on exit.

When output is piped or run without an interactive terminal (for example in CI), `dev`
falls back to a plain append-style status list and quits on `q`, so it still works headless.

### How status is detected

Status is inferred from each process's own output, so no extra configuration is needed for
the common stacks:

- **PecoTS backends** — marked `RUNNING` when the server logs its `Listening on port: <n>.`
  banner. A leading `[YYYY-MM-DD HH:MM:SS]` ConsoleLogger timestamp is tolerated.
- **Webpack / Pecular frontends** — `RUNNING` on `compiled successfully` (or
  `compiled with N warnings`).
- **`node --watch`** — `RESTARTING` on a watch restart, then `RUNNING` again.
- **Errors** — TypeScript (`error TSxxxx`), Webpack (`ERROR in …`, `Module not found`,
  `Failed to compile`) and fatal Node/PecoTS startup errors (`EADDRINUSE`, an uncaught
  `Error:`/`ReferenceError:`/`TypeError:` at the start of a line, or a PecoTS `ERROR:` log
  line) move the process to `ERROR`. Error signals take precedence over ready signals.

If your process announces readiness differently, set a per-process `ready` regular
expression in `peco-cli.yml`; a line matching it marks that process `RUNNING`.

### Troubleshooting

- **`No peco-cli.yml found …`** — the command only runs in a directory containing a
  `peco-cli.yml`. Create one as shown above.
- **`Invalid peco-cli.yml: …`** — the file is not valid YAML; the parser message follows.
- **Schema errors** (for example empty `processes`, a profile referencing an unknown key,
  or wrong value types) — the config fails closed and each problem is listed; no process
  starts.
- **`Unknown process or profile "…"`** — the selection token did not match a process key,
  a profile or `all`; the available processes and profiles are listed.
- **`CRASHED` on start** — usually a bad `command`/`cwd` (for example an `ENOENT` when the
  executable cannot be found). Check the `command` and `cwd` for the process.

### Security

`peco-cli dev` runs the commands declared in `peco-cli.yml` as child processes. Commands
are executed directly with no shell, so config values cannot be interpreted as shell
metacharacters, but the declared programs still run with your permissions. Only run
`peco-cli dev` in projects you trust — the same caution you would apply to `npm start`.
Environment values are never printed by the status view; only process keys and statuses
are shown.

## Executing your CLI

You may execute your CLI application built in PecoTS by calling this utility from the root folder of your application followed by the commands you have created or those provided by the framework.

```
peco-cli my-app-command.a-function-to-execute
peco-cli migration.make users
peco-cli rbac.make
peco-cli migration.up
peco-cli migration.down
```

## Security

When run without a built-in command, PecoCLI executes your project by importing its entry point (`index.ts`/`index.js`, a `./backend` entry, or the path in `PECOTS_BACKEND_PATH`). It also reads a `.env` from the current directory, which can set `PECOTS_BACKEND_PATH`. Because this runs project code in-process, only run `peco-cli` inside directories you trust — the same caution you would apply to `npm start` or running a project's scripts.

## Monorepo Configuration

For monorepo structures where your backend project is not located in the standard `./backend` directory, you can configure the backend path using the `PECOTS_BACKEND_PATH` environment variable.

### Environment Variable

Set the `PECOTS_BACKEND_PATH` environment variable to specify the path to your backend project:

```bash
# For relative paths (resolved from current working directory)
export PECOTS_BACKEND_PATH=packages/api/backend

# For absolute paths
export PECOTS_BACKEND_PATH=/full/path/to/backend
```

### Using .env Files

Alternatively, create a `.env` file in your project root:

```env
# .env file in project root
PECOTS_BACKEND_PATH=packages/api/backend
```

### Common Monorepo Examples

**Lerna/Nx Style:**

```env
PECOTS_BACKEND_PATH=packages/api
```

**Apps/Packages Structure:**

```env
PECOTS_BACKEND_PATH=apps/server
```

**Nested Backend:**

```env
PECOTS_BACKEND_PATH=services/backend/api
```

**Workspace Structure:**

```env
PECOTS_BACKEND_PATH=workspaces/backend
```

### Discovery Order

The CLI searches for your backend project in the following order:

1. **Environment Variable Path** - If `PECOTS_BACKEND_PATH` is set (from environment or .env file)
2. **Current Directory** - Looks for `index.ts` or `index.js` in the current directory
3. **Backend Subdirectory** - Looks for `index.ts` or `index.js` in `./backend/`

The CLI will automatically change to the backend directory during execution and return to the original directory when complete.

## Copyright

Copyright [Pecometer Software Limited](https://www.pecometer.co.uk)

---
_Source: https://npm.io/package/@pecometer/peco-cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._