Cipher Scope

Runtime visibility for modern applications. A terminal CLI that surfaces project context before you run anything — branded banner, env profile, package manager, and version from one config file.

TypeScript • Node.js • CLI • TOML

About Cipher Scope

Runtime visibility for modern applications. A terminal CLI that surfaces project context before you run anything — branded banner, env profile, package manager, and version from one config file.

Cipher Scope gives developers instant runtime visibility in the terminal. From a single cipherscope.toml file it prints a branded banner plus detected project facts — environment profile, package manager, and version — before you run builds or services.

Install it from npm as cipher-scope and use it in local workflows or CI to make project context obvious at a glance. Cipher Scope is maintained by Cipher Unit as a lightweight open-source CLI for modern TypeScript and Node.js repositories.

README.md

View on GitHub →

CipherScope

Project context in your terminal — before you run anything.

CipherScope is a small CLI that prints a branded ASCII banner plus auto-detected project facts. Everything is controlled from one file: cipherscope.toml.

 ██████╗██╗██████╗ ██╗  ██╗███████╗██████╗ ███████╗ ██████╗ ██████╗ ██████╗ ███████╗
██╔════╝██║██╔══██╗██║  ██║██╔════╝██╔══██╗██╔════╝██╔════╝██╔═══██╗██╔══██╗██╔════╝
██║     ██║██████╔╝███████║█████╗  ██████╔╝███████╗██║     ██║   ██║██████╔╝█████╗
██║     ██║██╔═══╝ ██╔══██║██╔══╝  ██╔══██╗╚════██║██║     ██║   ██║██╔═══╝ ██╔══╝
╚██████╗██║██║     ██║  ██║███████╗██║  ██║███████║╚██████╗╚██████╔╝██║     ███████╗
 ╚═════╝╚═╝╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═════╝ ╚═╝     ╚══════╝

Project
  Env              development  (.env.development)
  Package Manager  pnpm
  Version          1.2.3

Developer
  Name     CipherUnits
  Website  https://cipherunits.xyz
  GitHub   https://github.com/cipherunits

Features

Feature	What it does
ASCII banner	Renders `[project].name` in 5 weights (`thin` → `heavy`)
Project info	Auto-detects env profile, package manager, and app version
Developer block	Name, website, and GitHub — clickable in supported terminals
One config file	All toggles live in `cipherscope.toml`
npm script hook	`init` injects `cipherscope` as the first script in `package.json`

Coming later: Git status, Docker context, env var panel, themes, and cipher-scope run.

Install

npm install -g cipher-scope

Or use without a global install:

npx cipher-scope

Requires Node.js 18+.

Quick start

1. Initialize

In your project root:

npx cipher-scope

This will:

Create cipherscope.toml
Add this as the first script in package.json:

{
  "scripts": {
    "cipherscope": "cipher-scope banner",
    "dev": "next dev"
  }
}

2. Wire it into your workflow

{
  "scripts": {
    "cipherscope": "cipher-scope banner",
    "dev": "npm run cipherscope && next dev",
    "start": "npm run cipherscope && node dist/server.js"
  }
}

3. Run

npm run cipherscope
# or
npx cipher-scope banner

Configuration

All behavior is driven by cipherscope.toml.

[project]
name = "My Project"

[brand]
enabled = true
# thin | light | regular | bold | heavy
style = "heavy"

[info]
enabled = true
env = true
package_manager = true
version = true

[developer]
enabled = false
name = ""
website = ""
github = ""

`[project]`

Key	Type	Default	Description
`name`	string	`"My Project"`	Text rendered in the ASCII banner

`[brand]`

Key	Type	Default	Description
`enabled`	bool	`true`	Show / hide the banner
`style`	string	`"heavy"`	Banner weight

Styles (thin → heavy):

Value	Look
`thin`	Compact, small letters
`light`	Slanted, light stroke
`regular`	Classic standard
`bold`	Large block letters
`heavy`	Dense shadow block (ANSI Shadow)

`[info]`

Auto-detected facts. Turn the whole block off with enabled, or toggle each row.

Key	Type	Default	Description
`enabled`	bool	`true`	Show the project info block
`env`	bool	`true`	Active `.env` profile (`development`, `staging`, …)
`package_manager`	bool	`true`	`npm` / `pnpm` / `yarn` / `bun` (from lockfiles)
`version`	bool	`true`	Version from the project’s `package.json`

Env detection order

NODE_ENV when set (development, staging, production, …)
Otherwise the first existing file among:

.env.local → .env.development / .env.dev → .env.staging / .env.stage → .env.production / .env.prod → .env.test → .env

Package manager detection

pnpm-lock.yaml → yarn.lock → bun.lock / bun.lockb → package-lock.json → npm_config_user_agent

`[developer]`

Key	Type	Default	Description
`enabled`	bool	`false`	Show the developer block
`name`	string	`""`	Person or team name
`website`	string	`""`	Website URL (OSC-8 link when supported)
`github`	string	`""`	GitHub URL (OSC-8 link when supported)

Example:

[developer]
enabled = true
name = "CipherUnits"
website = "https://cipherunits.xyz"
github = "https://github.com/cipherunits"

CLI

Command	Description
`cipher-scope`	Create `cipherscope.toml` + inject the npm script
`cipher-scope init`	Same as above
`cipher-scope banner`	Print banner, project info, and developer block

Programmatic use

import {
  loadConfig,
  renderBanner,
  detectEnv,
  detectPackageManager,
  detectAppVersion,
} from "cipher-scope";

const config = loadConfig();
console.log(renderBanner(config.project.name, config.brand.style));
console.log(detectEnv());
console.log(detectPackageManager());
console.log(detectAppVersion());

Development

git clone https://github.com/cipherunits/CipherScope.git
cd CipherScope
pnpm install
pnpm build