hafiz CLI

Installable command-line client for the Hafiiz Admin portal.
It does not encrypt secrets itself — it logs you in via the browser and calls the portal API to fetch decrypted env files.

Language & stack

| Choice | Why | |--------|-----| | TypeScript on Node.js 18+ | Same ecosystem as the Next.js portal; native fetch; easy npm publish | | commander | Simple command parsing (login, fetch, …) | | Compiled to JS (tsc → dist/) | Users install a normal npm package; no TS runtime required |

This is intentional: a Node/npm CLI so anyone can run:

npm i -g @ali0548/cli
hafiz login
hafiz fetch my-org/api

Other languages (Go, Rust, Python) would also work, but npm is the fastest path to distribute a tool that talks to this portal.

Requirements

• Node.js 18+
• A running Hafiiz Admin portal (local or deployed)
• Portal NEXT_PUBLIC_APP_URL set to the public origin (so browser login links work)

Install (users)

# After you publish (see below)
npm i -g @ali0548/cli

# Point at your portal if not localhost
export HAFIZ_API_URL=https://your-portal.example.com   # macOS / Linux
setx HAFIZ_API_URL https://your-portal.example.com     # Windows (new terminals)

Local development (this repo)

cd hafiz.cli.sh
npm install
npm run build
npm link          # makes `hafiz` available globally from this folder

Or without linking:

npm run dev -- login
npm run start -- whoami

Commands

| Command | What it does | |---------|----------------| | hafiz login | Device + browser login; saves JWT to ~/.hafiz/credentials.json | | hafiz logout | Deletes local credentials | | hafiz whoami | GET /api/auth/me | | hafiz fetch <repo> [--out path] | GET /api/cli/env?repo= → writes env file (default ./.env) | | hafiz list | GET /api/envs — repos with a saved vault env | | hafiz search <query> | Search repos; print if they exist and dump env when saved | | hafiz scan | Scan current + child folders; write vault env (default .env.local) | | hafiz scan sub | Same, but child folders only |

Examples

$ hafiz login
Opening browser to authorize…
If it doesn’t open, visit:
  https://cli.app.hafiz.live/cli/authorize?user_code=DHXN-5ZK7

Code: DHXN-5ZK7
Waiting for approval…
✓ Logged in as [email protected]

$ hafiz fetch my-org/api
✓ Wrote .env (1240 bytes) — my-org/api

$ hafiz fetch api --out ./.env.local
✓ Wrote ./.env.local (1240 bytes) — my-org/api

$ hafiz scan
$ hafiz scan --file .env --mode create
$ hafiz scan sub --mode update

Scan modes

| Mode | Behavior | |------|----------| | --mode create | Write only if the file is missing; skip if it exists | | --mode update | Create if missing, overwrite if present | | (omit) | Create if missing; if present, ask y/n |

Config / env

| Variable | Purpose | |----------|---------| | HAFIZ_API_URL or HAFIZ_BASE_URL | Portal origin (no trailing slash). Default: https://cli.app.hafiz.live | | HAFIZ_TOKEN | Optional JWT for CI (skips browser login) |

Credentials file:

• Windows: %USERPROFILE%\.hafiz\credentials.json
• macOS / Linux: ~/.hafiz/credentials.json (mode 0600 when supported)

How to publish to the npm registry

1. One-time: npm account

1. Create an account at https://www.npmjs.com/signup
2. Enable 2FA (recommended)
3. On your machine:

npm login
npm whoami

2. Check the package name is free

This package is named @ali0548/cli in package.json (bin: hafiz).

npm view @ali0548/cli

• If that prints package info, the name is already taken — change "name" and keep "bin": { "hafiz": "bin/hafiz.js" } so the command stays hafiz.
• Scoped packages require --access public on first publish.

3. Build & dry-run

npm run build
npm pack --dry-run
# Should list dist/*.js and README.md — not src/ or node_modules/

Optional: install the tarball locally to test:

npm pack
npm i -g ./hafiz-0.1.0.tgz
hafiz --help

4. Publish

# First public release
npm publish --access public

# Later releases: bump version first
npm version patch   # 0.1.0 → 0.1.1  (also creates a git tag if in a repo)
npm publish

prepublishOnly runs npm run build automatically before publish.

5. Users install

npm i -g @ali0548/cli
# or whatever name you published

Version tips

| Command | Use when | |---------|----------| | npm version patch | Bug fixes | | npm version minor | New commands / compatible features | | npm version major | Breaking CLI changes |

Push tags if you use GitHub Releases:

git push && git push --tags

Common publish mistakes

• Forgetting to build — fixed by prepublishOnly
• Publishing src/ only — "files": ["dist", "README.md"] keeps the tarball small
• Wrong name — always npm view <name> first
• Private by default for scoped packages — use --access public for free public scoped packages
• Portal URL — users must set HAFIZ_API_URL to your deployed portal; localhost only works on their machine if the portal runs locally

Project layout

hafiz.cli.sh/
  package.json          # name, bin, publish config
  tsconfig.json
  src/
    index.ts            # entry + command registration
    api/client.ts       # HAFIZ_API_URL, Bearer, JSON envelope
    auth/login.ts       # device code + browser + poll
    auth/credentials.ts # ~/.hafiz/credentials.json
    commands/           # login, logout, whoami, fetch, list
  dist/                 # compiled output (published)

Portal (separate repo)

This CLI talks to the hafiz.cli Next.js app (API only). Do not put CLI code in the portal.

Relevant portal endpoints:

| Method | Path | Auth | |--------|------|------| | POST | /api/cli/device/code | no | | POST | /api/cli/device/token | no | | GET | /api/cli/env?repo= | Bearer | | GET | /api/auth/me | Bearer | | GET | /api/envs | Bearer |

License

MIT