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 while remaining fast and scriptable via command-line arguments.

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

Alias Mode (Direct)

bash

$pu uat cokesauat 300579

Arguments: [environment] [lob] [loginId]

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 promo

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

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

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.

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

CLI Commands Reference

Command	Description
pu	Open main interactive menu
pu env [path]	Configure secrets from file
pu [env] [lob] [login-id]	Get authentication token (direct)
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 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

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
m	manage	pu m
rm	remove-clone	pu rm mycontainer
u	update	pu u
s	setup	pu s channelkart
h	help	pu h

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 command pulls the latest source and rebuilds the binary.

bash

$pu update

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.