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).

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/

Drop Cache

Clear backend caches for Channelkart (entire LOB) or Promos Service (specific domain) across any environment. The CLI automatically generates an integration_user token for authentication.

Channelkart

Clears the entire cache for a specific LOB in the selected environment.

Promos Service

Clears a specific domain cache (e.g., Metadata) for a LOB in the selected environment.

Interactive Mode

Launch the guided workflow from the main menu or use the direct command.

bash

$pu
?Select: Drop Cache

Direct Access

bash

$pu drop-cache
$pu dc

Workflow Preview

promo-utils — drop-cache

?Select service: Channelkart (Entire LOB)
?Select Environment: UAT
?Select LOB: cokecvuat
⚠️  CAUTION: You are about to drop cache!
Type "yes" to confirm: yes
Generating token for integration_user...
Dropping Channelkart cache...
✔Cache Dropped Successfully!

How it works:

Select the service (Channelkart or Promos Service).
Choose the target environment (UAT, Demo, or Prod).
Select the LOB from the fetched list.
For Promos Service: Enter the domain name (default: Metadata).
Type "yes" to confirm the cache drop.
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

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. No manual registry config or Maven builds required.

promos-ui

schemes-service

channelkart

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

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

bash

$pu setup channelkart
$pu setup channelkart myprofile

Schemes Service

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

bash

$pu setup schemes-service
$pu setup schemes-service default

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 drop-cache	Drop cache for Channelkart or Promos Service
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 channelkart [profile]	Initialize Channelkart project
pu setup promos-ui	Initialize Promos-UI project
pu setup schemes-service [profile]	Initialize Schemes Service
pu update	Update CLI to latest version
pu help	Show help message
pu pre-script	Copy validate-to-calculate prescript to clipboard

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

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.