@pecometer/peco-cli

PecoCLI

A command line app that is primarily used to setup a Node.js project with PecoTS (backend) and Angular (frontend) as the main frameworks. PecoTS 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

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:

# 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 file in project root
PECOTS_BACKEND_PATH=packages/api/backend

Common Monorepo Examples

Lerna/Nx Style:

PECOTS_BACKEND_PATH=packages/api

Apps/Packages Structure:

PECOTS_BACKEND_PATH=apps/server

Nested Backend:

PECOTS_BACKEND_PATH=services/backend/api

Workspace Structure:

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