Documentation

Introduction

Promo Utils is a powerful CLI companion for the Promos team. It automates repetitive tasks like token retrieval, database cloning, and service initialization.

Built with React (Ink), it provides a rich interactive interface, fast scriptable commands, and an intelligent AI agent to handle complex workflows for you.

Installation

Bootstrap via CLI

The fastest way to get started. Clone and run the automated install script:

bash

$git clone https://github.com/akshatdubey-salescode/promo-utils
$cd promo-utils
$chmod +x install.sh
$./install.sh

Manual Setup

If you prefer granular control over the installation:

bash

$npm install
$npm run build
$npm link

Quick Start

First-time setup requires linking your environment configuration. This file stores your API and DB credentials securely.

bash

$pu env /path/to/.env.config
# Configuration saved to ~/.promo-utils/config.env

$# Launch interactive menu
$pu

Authentication

Generate access tokens for any LOB across UAT, Demo, or Production. Tokens are automatically copied to your clipboard.

Interactive Mode

Run pu and select "Get Token".

promo-utils — get-token

?Select environment: UAT
?Select LOB:Unlimited Expiry: ON (Press U to toggle)No Store Token: OFF (Press S to toggle)
❯cokecvuat

Alias Mode (Direct)

bash

$pu uat cokesauat 300579
# For unlimited expiry token:
$pu uat cokesauat 300579 -U
# For no store token:
$pu uat cokesauat 300579 -S
# For unlimited no store token:
$pu uat cokesauat 300579 -U -S

Arguments: [environment] [lob] [loginId] [-U] [-S]

Use the -U flag to request an unlimited expiry token.

Use the -S flag to request a no store token (sends &nostore=true to API).

Region Targeting

Production is deployed across three geographic regions. Any feature that interacts with a production environment requires a region to be specified so requests are routed to the correct cluster.

ap (default)

Asia Pacific

eu

Southern Europe

us

US West

Interactive Mode

Whenever you select Prod as the environment, a region selection screen is shown automatically before the LOB list is fetched.

promo-utils — get-token

?Select environment: Prod
?Select prod region:
❯Asia Pacific (default)
 Southern Europe
 US West

Direct / Alias Mode

Pass a region flag alongside the environment argument. The flag can appear anywhere in the command.

bash

# Asia Pacific (ap is the default, flag is optional)
$pu prod cokecvprod 300579 --ap

# Southern Europe
$pu prod cokecvprod 300579 --eu

# US West
$pu prod cokecvprod 300579 --us

# Works with health-check too
$pu hc prod ck --eu

Flag Aliases

--ap

also: --asia, --apac

--eu

also: --europe, --south-europe

--us

also: --west, --us-west

Supported Features

Region targeting applies to all features that communicate with the production backend:

Get Token
Manage Cache (Drop Cache & Get Cache Key)
Health Check
Manage Configs
Promotions Helpers
AI Agent (Casper) — specify region in your prompt, e.g. "get token for cokecvprod in eu"

AI Agent (Casper)

Casper is an intelligent agent built into the CLI that can understand natural language requests and execute complex workflows for you.

Interactive Mode

Launch the agent and start chatting.

bash

$pu ai
?What can Casper do for you?
>Get me an unlimited token for ckcoeuat

One-Shot Mode

Execute a specific task directly from the command line.

bash

$pu ai generate token for niineuat
$pu ai clone demo niinedemo on port 5433

Capabilities:

Token generation (standard, unlimited expiry, no-store)
Database cloning and management
Cache clearing (Channelkart & Promos)
Table exports
Health checks
Context-aware assistance and chaining commands

Database Cloning

Clone remote UAT/Demo databases to your local machine using Docker. This allows you to debug with real data safely.

How it works:

CLI connects to the remote environment.
Initializes a local Docker container with the correct Postgres version.
Streams the database dump directly into your local container.
Sets up port forwarding so you can connect via any DB client.

Interactive Mode

Launch the full interactive workflow from the main menu.

bash

$pu
?Select: Clone Database

Direct Clone

bash

$pu clone uat digivyaparuat
$pu clone demo niinedemo mycontainer
$pu clone uat cokesauat mydb 7005

Arguments: <environment> <remote-db-name> [container-name] [port]

Export Table

Export one or more tables from remote databases to SQL files. Supports UAT, Demo, and Production environments.

Interactive Mode

Launch the interactive export workflow from the main menu.

bash

$pu
?Select: Export Table

Direct Export

bash

$pu export uat digivyaparuat definition
$pu export demo niinedemo definition budget_ledger
$pu export prod ckcoedemo definition budget_ledger parallel_filters

Arguments: <environment> <db-name> <table1> [table2] [table3] ...

Exported files are saved to ~/Downloads/table-backups/

Manage Cache

Manage backend caches across environments. You can either clear caches for entire LOBs/domains or inspect live cache values for specific keys.

Drop Cache

Clear caches for Channelkart (entire LOB) or Promos Service (specific domain).

Get Cache Key

Inspect the current live value of any key within a specific cache domain.

Interactive Mode

Launch the guided workflow from the main menu.

bash

$pu
?Select: Manage Cache
?Select: Get Cache Key

Direct Access (Drop Cache)

bash

$pu drop-cache
$pu dc

How it works:

Select the action (Drop Cache or Get Cache Key).
Choose the target environment (UAT, Demo, or Prod).
Select the LOB from the fetched list.
For Get Cache Key: Select or enter the domain and provide the key.
CLI generates an integration_user token and executes the request.

Health Check

Monitor the status of your services in real-time. The health check command provides detailed information about releases, versions, commit history, and system types.

Channelkart

View release names, versions, system info, and commit details for Channelkart.

Promos Service

Check service status, build time, and last commit information for the Promos Service.

Interactive Mode

Launch the health check menu from the main screen or use the direct command.

bash

$pu
?Select: Health Check

Direct Access

bash

$pu health-check
$pu hc uat ck
$pu hc demo ss

Direct syntax: pu hc <environment> <service>

Service options: ck (Channelkart) or ss (Promos/Schemes Service).

Result Preview

promo-utils — health-check

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Channelkart Health Check - UAT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Release Information:
  Release Name: Channelkart-UAT-Main
  Version:      2.4.0
  System Type:  K8S

Commit Information:
  Branch:       release/v2.4
  Commit ID:    a1b2c3d4e5f6...
  Message:      feat: implement health check endpoint

Manage Configs

Manage environment configuration metadata (Configs) directly from the CLI. This feature allows you to list all configurations, view specific key details, and create or update configuration values.

LOB-Specific

Configs are scoped to specific LOBs in UAT, Demo, and Prod environments.

Local Support

Easily manage configs for your local development environment via port mapping.

Interactive Mode

Access the config manager from the main menu.

bash

$pu
?Select: Manage Configs

Workflow Preview

promo-utils — manage-configs

?Select Environment: UAT
?Select LOB: cokecvuat
?Select Action: List All Configs

All Configs (42 total):
❯ ● promo.engine.enabled
  ● max.discount.limit
  ○ maintenance.mode

Key Capabilities:

List All: Browse all configuration keys and their descriptions.
View Detail: See the current value, active status, and modification history of any key.
Upsert: Create new keys or update existing ones with JSON or plain string values.
Audit Logs: All changes made via the CLI are logged with the user's email and environment details.

ckroot Profile Management

Tenant database credentials in the local ckroot MySQL database rotate every few hours. Instead of manually running SQL each time, the CLI lets you update a tenant's profile entry in seconds — either by walking through a guided form or by pasting a MySQL connection string directly.

One-time setup

Before using this feature, save your local ckroot MySQL connection details so the CLI knows how to connect. Go to More Options... → Settings → Manage ckroot Credentials and enter your host, port, username, and password.

promo-utils — settings

?Select: More Options...
?Select: Settings
?Select: Manage ckroot Credentials
Host: localhost
Port: 3306
Username: root
Password: ••••••
✔ckroot credentials saved

Interactive Mode — Paste MySQL Command

Select Update ckroot Profile from the main menu. Choose Paste MySQL command, paste the connection string you received, and the CLI parses it automatically — then takes you straight to the confirm screen.

promo-utils — ckroot-profile

?How would you like to enter credentials?
❯Paste MySQL command (auto-parse)
 Enter manually (step by step)

Command: mysql -h 192.168.1.100 -P 6033 -u trustgate_user -p'R0tatedP@ss!' db_hfcoeuat -A

Confirm ckroot Profile Update
  LOB:      hfcoeuat
  DB name:  db_hfcoeuat
  Host:     192.168.1.100
  Port:     6033
  Username: trustgate_user
  Password: ••••••••••••

❯Confirm — run upsert
 ← Back

✔ckroot profile updated: hfcoeuat

Interactive Mode — Manual Entry

Choose Enter manually to walk through each field one at a time: LOB name, host, port, username, and password.

promo-utils — ckroot-profile

LOB name: hfcoeuat
Host: 192.168.1.100
Port: 6033
Username: trustgate_user
Password: ••••••••••••

Direct Mode — Paste & Go

The fastest path. Copy the MySQL command you received and pass it directly to pu profile. The CLI parses the flags, runs the upsert, and exits — no prompts.

bash

$pu profile mysql -h 192.168.1.100 -P 6033 -u trustgate_user -p'R0tatedP@ss!' db_hfcoeuat -A
# Alias
$pu p mysql -h 192.168.1.100 -P 6033 -u trustgate_user -p'R0tatedP@ss!' db_hfcoeuat -A

✓ ckroot profile updated: hfcoeuat
  db_name: db_hfcoeuat
  host:    192.168.1.100:6033
  user:    trustgate_user

The shell strips the single quotes around the password before passing it to the CLI, so special characters like &, *, and ! are handled safely.

How it works:

Reads your saved ckroot connection from ~/.promo-utils/config.env.
Builds the attributes JSON with the new credentials and a JDBC URL derived from the provided host, port, and LOB name.
Runs an INSERT ... ON DUPLICATE KEY UPDATE against your local ckroot database — inserting the row if it doesn't exist, or updating credentials if it does.

Manage Environment Variables

Settings also includes a raw config viewer. Select Manage Environment Variables to browse and edit any key in ~/.promo-utils/config.env directly from the CLI without opening a text editor.

promo-utils — settings

?Select: Manage Environment Variables
❯API_BASE_DOMAIN = salescode.ai
 UAT_REMOTE_DB_HOST = e2e-94-100.ssdcloud…
 CKROOT_DB_PORT = 3306
# Select a key to edit its value inline

Git Statistics

Analyze repository activity with a manager-level overview of branch distribution across authors. Track merge status, distinguish between local and remote work, and visualize contribution trends over time.

Author Overview

See total, merged, and pending branches for every contributor in a clean, sorted table.

Branch Drill-down

Select any author to see their full branch history, including last activity dates and source.

Contribution Graph

Visualize commit activity over the entire year with a GitHub-style heatmap. Navigate through years using Left/Right arrow keys.

UI Preview

promo-utils

Git Branch Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AuthorTotalMergedPending
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❯Tyler Durden1510 (4/6)5 (2/3)
 Harvey Specter128 (5/3)4 (1/3)
 Ra’s al Ghul87 (7/0)1 (1/0)
 Jake Peralta53 (2/1)2 (2/0)

JanFebMarAprMayJunJulAugSepOct
← 2024|2025|2026 →
Less
More

Showing item 1 of 4[Scroll Position: Top - 25%]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
↑/↓: Navigate | Enter: View Branches | 't': Filter | 'b': Back

Direct Access

bash

$pu git-stats
$pu gs

Keyboard Shortcuts:

←/→ - Cycle contribution years
t - Cycle filters (Remote Only → All → Local Only)
Enter - View author's branch details
Esc - Return to author list

Manage Clones

Keep track of your active database containers and clean up unused clones to save system resources.

List Active Clones

bash

$pu manage
🟢 mydb
   Status: Running
   Port:   7005

Lists all cloned databases with their status and port information.

Remove a Clone

bash

$pu remove-clone mydb

Permanently removes the specified database container.

View Database Size

When listing cloned databases, the CLI displays the size of each database to help you manage disk space.

bash

$pu manage
🟢 mydb
   Status: Running
   Port:   7005
   Size:   1.2 GB

5-Minute Idle Timeout

Cloned database containers automatically stop after 5 minutes of inactivity. This helps conserve system resources. Simply restart the container when you need to access the database again.

Zero-Config Setup

Instantly bootstrap local development for core Promos services. These commands are now conveniently grouped under the Initialise Projects menu in interactive mode.

promos-ui

schemes-service

channelkart

Interactive Setup

Launch the interactive menu and select "Initialise Projects" to see all available setup options.

bash

$pu
?Select: Initialise Projects

Promos-UI

Configures NPM with CodeArtifact, installs dependencies, and sets up environment registry.

bash

$pu setup promos-ui
Configuring npm with CodeArtifact...
Installing dependencies...
✔Success!

Channelkart / Schemes Service

Runs AWS SSO login and Maven builds with optional AWS profile.

bash

$pu setup channelkart [profile]
$pu setup schemes-service [profile]

Developer Prescripts

Access handy utility scripts for common development tasks. These pre-built scripts help you quickly transform and work with API requests in Postman.

Available Prescripts

Validate to Calculate Curl Converter

A Postman pre-request script that transforms a validate API curl command into a calculate API curl command. Useful when testing promotion calculations after validation.

Interactive Mode

Access prescripts from the "More Options" menu in interactive mode.

bash

$pu
?Select: More Options...
?Select: Copy pre-script to convert validate to calculate curl
✔Pre-script copied to clipboard!

Direct Access

bash

$pu pre-script
$pu ps
$pu prescript

Copies the prescript directly to your clipboard for immediate use.

How to use in Postman:

Copy the prescript using the CLI.
Open Postman and navigate to your collection or request.
Go to the "Pre-request Script" tab.
Paste the copied script into the editor.
When you send a validate request, the script automatically transforms it to a calculate request.

CLI Commands Reference

Command	Description
pu	Open main interactive menu
pu env [path]	Configure secrets from file
pu [env] [lob] [login-id] [-U] [-S]	Get authentication token (direct). Use `-U` for unlimited expiry, `-S` for no store tokens.
pu clone <env> <remote-db> [container] [port]	Clone remote database to local container
pu export <env> <db-name> <table1> [table2] ...	Export tables to SQL files
pu manage-cache	Manage caches (drop cache or get key value)
pu promo-helpers	Manage promotions (get details, activate, deactivate)
pu health-check	Check health status of various services
pu hc <env> <service>	Direct health check for ck or ss
pu git-stats	View git branch statistics by author
pu manage	List all cloned databases
pu remove-clone [name]	Remove a cloned database
pu setup <service>	Initialize project dependencies (promos-ui, channelkart, schemes-service)
pu update	Update CLI to latest version
pu help	Show help message
pu pre-script	Copy validate-to-calculate prescript to clipboard
pu profile mysql -h HOST -P PORT -u USER -p'PASS' db_LOB	Parse a MySQL command and upsert the tenant profile in ckroot

Command Aliases

Save time with built-in command shortcuts. All aliases can be used interchangeably with their full command names.

Alias	Full Command	Example
c	clone	pu c uat digivyaparuat
e	export	pu e demo niinedemo definition
ex	export	pu ex uat ckcoeuat budget_ledger
gs	git-stats	pu gs
git	git-stats	pu git
dc	drop-cache	pu dc
hc	health-check	pu hc uat ck
m	manage	pu m
rm	remove-clone	pu rm mycontainer
u	update	pu u
s	setup	pu s channelkart
h	help	pu h
ps	prescript	pu ps
pre-script	prescript	pu pre-script
p	profile	pu p mysql -h HOST -P PORT -u USER -p'PASS' db_LOB

Pro Tip: Aliases only work as the first argument. For example, use pu c uat dbname instead of pu uat c dbname.

Configuration

The .env.config file is the source of truth for your CLI. When you run pu env, the configuration is securely saved to:

~/.promo-utils/config.env

It must contain the following keys to function correctly:

.env.config

UAT_API_URL=...
DEMO_API_URL=...
PROD_API_URL=...
UAT_DB_HOST=...
ENCRYPTION_KEY=...

Update CLI

Stay up to date with the latest features and bug fixes. The update system includes OTP authentication and a version selector, allowing you to choose specific versions or roll back if needed.

OTP Authentication

Secure updates with email-based OTP verification. Your authentication is saved for future updates.

Version Selector

Choose any available version to install, not just the latest. Useful for rollbacks.

Interactive Mode

Access the update feature from the "More Options" menu.

bash

$pu
?Select: More Options...
?Select: Update Promo-Utils

Direct Access

bash

$pu update
$pu u

Update Workflow

promo-utils — update

🔄 Checking for updates...
📦 Current version: 1.1.2

🔐 Authentication required
?Enter your authorized email: user@example.com
📧 Requesting OTP...
✔OTP sent to your email!
?Enter 6-digit OTP: 123456
🔐 Verifying...
✔Authentication successful!

📦 Fetching available versions...
Available versions:
  1. 1.1.0
  2. 1.1.1
  3. 1.1.2 (current)
  4. 1.1.3 (latest)
?Select version to install (number): 4

📦 Selected version: 1.1.3
⬇️  Preparing download...
⬇️  Downloading package...
✔Download complete!
🔧 Installing package...

✔Update completed successfully!
📦 Updated to version: 1.1.3

How it works:

Enter your authorized email address for OTP verification.
A 6-digit OTP is sent to your email.
Enter the OTP to authenticate.
Your authentication is saved for future updates.
Select from available versions (including older versions for rollbacks).
The CLI downloads and installs the selected version.
Restart your terminal or run rehash (zsh) or hash -r (bash) to use the new version.

Token Expiration

If your saved authentication token expires, the CLI will prompt you to re-authenticate. Your email is preserved for convenience.

Troubleshooting

Docker Connection Failed

Ensure Docker Desktop is running and your user has permissions to access the docker socket.

Port Conflicts

If a port is already in use, choose a different one during the clone setup or run pu manage to stop existing clones.

View CLI Logs

If you encounter unexpected errors, you can check the local log file for detailed debugging information:

~/.promo-utils/logs.txt

Introduction

Installation

Bootstrap via CLI

Manual Setup

Quick Start

Authentication

Interactive Mode

Alias Mode (Direct)

Region Targeting

ap (default)

eu

us

Interactive Mode

Direct / Alias Mode

Flag Aliases

Supported Features

AI Agent (Casper)

Interactive Mode

One-Shot Mode

Capabilities:

Database Cloning

How it works:

Interactive Mode

Direct Clone

Export Table

Interactive Mode

Direct Export

Manage Cache

Drop Cache

Get Cache Key

Interactive Mode

Direct Access (Drop Cache)

How it works:

Promotions Helpers

Get Details

Activate

Deactivate

Interactive Mode

Result Preview

Health Check

Channelkart

Promos Service

Interactive Mode

Direct Access

Result Preview

Manage Configs

LOB-Specific

Local Support

Interactive Mode

Workflow Preview

Key Capabilities:

ckroot Profile Management

One-time setup

Interactive Mode — Paste MySQL Command

Interactive Mode — Manual Entry

Direct Mode — Paste & Go

How it works:

Manage Environment Variables

Git Statistics

Author Overview

Branch Drill-down

Contribution Graph

UI Preview

Direct Access

Keyboard Shortcuts:

Manage Clones

List Active Clones

Remove a Clone

View Database Size

5-Minute Idle Timeout

Zero-Config Setup

Interactive Setup

Promos-UI

Channelkart / Schemes Service

Developer Prescripts

Available Prescripts

Validate to Calculate Curl Converter

Interactive Mode

Direct Access

How to use in Postman: