From fc1d392fbaf9b9cc67f8bd5df8fe2c611e51eaad Mon Sep 17 00:00:00 2001
From: Dandy Royyan Firdaus <dandy.royyan.firdaus@gmail.com>
Date: Fri, 28 Aug 2026 01:16:44 +0700
Subject: [PATCH] add readme.md

---
 README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b83359e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,143 @@
+# OSMAP CLI - Embed Map Navigator & Token Manager
+
+A lightweight CLI tool for developers and administrators to manage authentication tokens and quickly navigate or launch OSMAP KAI embed map routes across different environments (`live`, `beta`, `staging`, `demo`, `local`).
+
+---
+
+## ⚡ Quick Start (No Installation Needed)
+
+### 1. Prerequisites
+- **Bash** (`Git Bash`, `WSL`, `Linux`, or `macOS`)
+- **`curl`**
+- **`jq`** (JSON processor)
+  - **Windows (PowerShell as Admin)**: `choco install jq -y`
+  - **Ubuntu / Debian / WSL**: `sudo apt update && sudo apt install -y jq`
+  - **macOS**: `brew install jq`
+
+---
+
+## 🚀 Running the CLI
+
+### Option A: Direct Execution via `curl`
+
+#### Using Git Bash / Linux / macOS:
+```bash
+curl -sSL https://git.oslog.pro/dandy/osmap_cli/raw/branch/main/osmap-embed.sh | bash
+```
+
+To pass arguments / flags:
+```bash
+# Open Executive Map directly in browser
+curl -sSL https://git.oslog.pro/dandy/osmap_cli/raw/branch/main/osmap-embed.sh | bash -s -- executive --env live --open
+
+# Get all embed URLs for beta environment
+curl -sSL https://git.oslog.pro/dandy/osmap_cli/raw/branch/main/osmap-embed.sh | bash -s -- all --env beta
+```
+
+#### Using Windows PowerShell:
+```powershell
+bash -c "curl -sSL https://git.oslog.pro/dandy/osmap_cli/raw/branch/main/osmap-embed.sh | bash"
+```
+
+---
+
+### Option B: Clone & Run Locally
+
+```bash
+git clone https://git.oslog.pro/dandy/osmap_cli.git
+cd osmap_cli
+chmod +x osmap-embed.sh
+
+# Launch Interactive Menu
+./osmap-embed.sh
+```
+
+---
+
+## 📖 Usage & Commands
+
+```bash
+./osmap-embed.sh [route|command] [options]
+```
+
+### Commands
+
+| Command | Description |
+| :--- | :--- |
+| `interactive` *(default)* | Opens an interactive CLI menu to pick routes, copy tokens, or switch environments |
+| `all` | Prints a formatted table of all map embed URLs with a valid token |
+| `token` | Fetches and prints the raw active access token only |
+| `validate` | Checks whether the locally cached token is still valid |
+| `revoke` | Revokes active tokens on the server and clears local cache |
+| `register` | Registers a new application and saves credentials |
+
+### Available Map Routes
+
+| Route Identifier | Map Name | Target Path |
+| :--- | :--- | :--- |
+| `executive` | Executive Map | `/executive` |
+| `rolling` | Rolling Map | `/rolling` |
+| `iris-jpl` | IRIS JPL | `/iris-jpl` |
+| `iris-jpl-v2` | IRIS JPL (v2) | `/v2/iris-jpl` |
+| `accelerometer` | Executive Accelerometer | `/executive/accelerometer` |
+| `genset` | Genset Monitoring | `/genset` |
+| `managerial` | Managerial / Asset View | `/managerial` |
+| `fatigue` | Fatigue Monitoring | `/fatigue` |
+| `sigap-tracker` | SIGAP Tracker | `/sigap-tracker` |
+| `sigap-dashboard` | SIGAP Dashboard | `/sigap-dashboard` |
+| `railway-cargo-system` | Railway Cargo System (RCS) | `/railway-cargo-system` |
+
+---
+
+## ⚙️ Options & Flags
+
+| Flag | Description | Default |
+| :--- | :--- | :--- |
+| `-e`, `--env <env>` | Target environment (`live`, `beta`, `staging`, `demo`, `local`, or custom URL) | `live` |
+| `-o`, `--open` | Automatically open the generated URL in your default browser | `false` |
+| `-c`, `--copy` | Automatically copy the URL to system clipboard | `false` |
+| `--app-id <id>` | Override App ID credential | Default Built-in / Env |
+| `--app-secret <sec>` | Override App Secret credential | Default Built-in / Env |
+| `--save` | Save provided `--app-id` and `--app-secret` to `.osmap_credentials` | `false` |
+| `-h`, `--help` | Show command line help and usage | - |
+
+---
+
+## 💡 Examples
+
+- **Interactive Menu (live environment):**
+  ```bash
+  ./osmap-embed.sh
+  ```
+
+- **Open IRIS JPL in browser on Live environment:**
+  ```bash
+  ./osmap-embed.sh iris-jpl --open
+  ```
+
+- **Get the raw token string for scripts / automation:**
+  ```bash
+  TOKEN=$(./osmap-embed.sh token --env live)
+  echo "Current Token: $TOKEN"
+  ```
+
+- **Open Managerial Map on Beta environment:**
+  ```bash
+  ./osmap-embed.sh managerial --env beta --open
+  ```
+
+- **Test against Local development server (`http://localhost:8000`):**
+  ```bash
+  ./osmap-embed.sh --env local
+  ```
+
+---
+
+## 🔐 Credentials & Configuration Precedence
+
+Credentials are automatically loaded in the following order:
+1. CLI Flags (`--app-id`, `--app-secret`)
+2. Environment Variables (`OSMAP_APP_ID`, `OSMAP_APP_SECRET`)
+3. Local config file (`.osmap_credentials`)
+4. Current directory `.env` file
+5. Built-in default credentials