7Star CLI ⭐

Professional API Deployment & Management CLI for 7Star Media backend.

Installation

# From npm (Private Package)
npm install -g 7star

# Or link locally for development
cd 7star-cli
npm install
npm link

Commands

| Command | Description | |-------------------|------------------------------------------------------| | 7star start | Start the API server via PM2 | | 7star stop | Stop the server safely | | 7star restart | Restart and verify the server | | 7star status | Show PID, CPU, RAM, Uptime, Port, Public URL | | 7star publish | Create a permanent free public URL (DuckDNS) | | 7star doctor | Diagnose environment & auto-fix issues |

Quick Start

# 1. Install globally
npm install -g 7star

# 2. Run the doctor to verify your environment
7star doctor

# 3. Start the API (auto-downloads backend if missing)
7star start

# 4. Check status
7star status

# 5. Create a public URL
7star tunnel

7star start

Starts the API server using PM2.

• ✅ Auto-downloads the backend from GitHub if not present
• ✅ Runs npm install if node_modules is missing
• ✅ Creates .env from .env.example if needed
• ✅ Verifies the service came online before reporting success
• ✅ Saves the PM2 process list for reboot persistence

7star start
7star start --port 4000      # Override port
7star start --skip-install   # Skip npm install step

After first start, edit the .env file:

~/.7star/backend/.env

Set your Supabase credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
PORT=3000

Then restart: 7star restart

7star stop

7star stop           # Stop the service
7star stop --force   # Stop AND remove from PM2 list

7star restart

7star restart   # Restart and verify online status

7star status

7star status          # Human-readable status table
7star status --json   # Machine-readable JSON output

Output includes:

• Service status badge (ONLINE / STOPPED / ERROR)
• PID
• CPU usage %
• RAM usage (MB)
• Uptime
• Restart count
• Version
• Port
• Public tunnel URL (if active)

7star tunnel

Creates a public HTTPS URL for your local API.

Priority order:

1. 🔵 Cloudflare Tunnel (cloudflared must be installed)
2. 🟡 LocalTunnel (auto-installed via npm if needed)

7star tunnel                         # Auto-select provider
7star tunnel --provider cloudflare   # Force Cloudflare
7star tunnel --provider localtunnel  # Force LocalTunnel
7star tunnel --port 4000             # Custom local port

The public URL is saved to ~/.7star/config.json and displayed in 7star status.

Install Cloudflare Tunnel (recommended):

# Windows
winget install --id Cloudflare.cloudflared

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

7star doctor

Checks your environment and reports issues:

| Check | What it verifies | |--------------------|-----------------------------------------| | Node.js | Version ≥ 18 | | npm | Version ≥ 8 | | Git | Available for cloning | | PM2 | Installed globally | | Port | Target port is free | | Internet | Can reach github.com | | Permissions | Can write to ~/.7star/ | | Cloudflared | Optional tunnel client | | Backend Project | Backend files present |

7star doctor          # Check only
7star doctor --fix    # Check and auto-fix where possible

Configuration

All settings are stored in ~/.7star/config.json:

{
  "project": {
    "name": "7star-api",
    "pm2AppName": "7star-api",
    "port": 3000,
    "dir": "/home/user/.7star/backend",
    "githubRepo": "youssef-official/lovelace-sales-hub",
    "branch": "main",
    "subDir": "backend"
  },
  "tunnel": {
    "provider": "cloudflare",
    "url": "https://xxx.trycloudflare.com",
    "lastUpdated": "2025-01-01T00:00:00.000Z"
  }
}

Logs

All operations are logged to ~/.7star/logs/:

| File | Content | |--------------------|-------------------------------| | combined.log | All log levels (JSON) | | error.log | Errors only (JSON) | | exceptions.log | Unhandled exceptions |

Enable debug output:

DEBUG=1 7star start

Project Structure

7star-cli/
├── bin/
│   └── 7star.js              # CLI entry point (shebang)
├── src/
│   ├── cli.js                # Commander.js bootstrap
│   ├── config.js             # Configuration manager (~/.7star/)
│   ├── commands/
│   │   ├── start.js          # 7star start
│   │   ├── stop.js           # 7star stop
│   │   ├── restart.js        # 7star restart
│   │   ├── status.js         # 7star status
│   │   ├── tunnel.js         # 7star tunnel
│   │   └── doctor.js         # 7star doctor
│   └── utils/
│       ├── ui.js             # Terminal UI (chalk, ora, figlet)
│       ├── logger.js         # Winston logger
│       ├── pm2.js            # PM2 wrapper
│       └── project.js        # Project setup & GitHub download
├── package.json
├── .gitignore
└── README.md

Platform Support

| Platform | Status | Notes | |----------|---------|-----------------------------------| | Linux | ✅ Full | Recommended for production VPS | | macOS | ✅ Full | Development & testing | | Windows | ✅ Full | Tested on PowerShell & cmd |

Publishing as Private NPM Package

# Login to your npm account or private registry
npm login

# Publish (restricted access = private)
npm publish

# Install on any server
npm install -g 7star

Development

# Install deps
npm install

# Link globally for testing
npm link

# Test commands
7star doctor
7star start
7star status

# Unlink when done
npm unlink -g 7star

License

MIT © 7Star Media Team