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.com
  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:

1. Create cipherscope.toml
2. 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

1. NODE_ENV when set (development, staging, production, …)
2. 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.com"
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

Local pack & smoke test:

npm pack
# in a throwaway folder:
npm install /path/to/cipher-scope-0.0.3.tgz
npx cipher-scope
npm run cipherscope

Publish:

npm publish

---

Roadmap

• Init + cipherscope.toml
• npm script injection
• 5-weight ASCII banners
• Auto project info (env / PM / version)
• Developer links
• Git status panel
• Docker context
• Env var panel with secret redaction
• Themes & richer UI modes
• cipher-scope run <script>

Full plan: CipherScope_Roadmap.md

---

License

MIT © CipherUnits