A beautiful, interactive terminal-based client for the Greenlight API, built with BubbleTea and Lip Gloss.
Manage movies, users, and tokens from your terminal with a rich, navigable TUI.
- 🔗 Connect to any Greenlight API — Set the base URL on launch with automatic health verification.
- 🔐 Full Authentication Flow — Login, register, activate account, forgot/reset password.
- 🎬 Movie Management — List, search, create, edit, and delete movies with confirmation prompts.
- 🔎 Advanced Search & Filtering — Filter movies by title, genres, year, runtime, or ID using inline overlays.
- 📄 Pagination — Navigate multi-page result sets with arrow keys.
- 📋 Raw JSON Viewer — Inspect full API responses for any movie, ready to copy.
- 🏥 Health Check — View API status, environment, and version at a glance.
- ⚙️ Account Settings — View your profile, reset your password, or log out.
- 🛡️ Safety Prompts — Confirmation dialogs before destructive actions (delete, edit save).
- Go 1.25+
- A running instance of the Greenlight API
- Just command runner (optional but recommended)
There are two ways to install the Greenlight CLI:
You can download the latest pre-compiled executables for Linux, Windows, and macOS directly from the GitHub Releases page. Simply extract the binary matching your operating system and run it directly in your terminal.
If you prefer to build the project yourself, ensure you have Go 1.25+ installed:
# Clone the repository
git clone https://github.com/nil-omen/greenlight-client.git
cd greenlight-client
# Install dependencies
go mod tidy
# Build the binary
just build
# or without just:
go build -o ./bin/client ./cmd/cli# If running a downloaded release:
./greenlight-client-linux-amd64
# If running from source (Dev mode):
just run
# Or run the compiled source binary:
./bin/clientOn launch, you'll be prompted to enter your Greenlight API URL (e.g., http://localhost:4000). The client will verify the connection via the health check endpoint before proceeding.
The app uses a consistent set of keybindings across all views:
| Key | Action |
|---|---|
↑ / ↓ |
Navigate menu items / table rows |
enter |
Select / submit |
esc |
Go back to previous screen |
tab / shift+tab |
Next / previous form field |
ctrl+c |
Quit the application |
When the app launches, enter the base URL of your Greenlight API:
┌─ Set API URL ──────────────────────────┐
│ │
│ Enter Greenlight API URL: │
│ > http://localhost:4000 │
│ │
│ enter: connect • ctrl+c: quit │
└────────────────────────────────────────┘
The client automatically calls GET /v1/healthcheck to verify the connection.
After connecting, you'll see the onboarding menu:
> 1. Login
2. Create New User
3. Activate User
4. Forgot Password
Enter your email and password. On success, the authentication token is stored in memory and used for all subsequent API calls.
Register with a name, email, and password. After successful registration, you'll be redirected to the activation page.
Enter the activation token sent to your email to activate your account.
Enter your email to receive a password reset token, then use it on the reset page with your new password (entered twice for confirmation).
Once authenticated, the dashboard provides access to all features:
Greenlight Dashboard
> 1. List / Search Movies
2. Add New Movie
3. Health Check
4. Account Settings
5. Exit
↑/↓: navigate • enter: select • ctrl+c: quit
The movie list defaults to showing the 10 most recently added movies (sort=-id, page_size=10).
Press any of these keys while in the list view to open a search overlay:
| Key | Filter | Example Input |
|---|---|---|
t |
Title | moana |
g |
Genres | action, adventure |
y |
Year | 2016 |
r |
Runtime | 107 or 107 mins |
i |
ID | 1 |
Note: Genres accept both
action,adventureandaction, adventure(spaces are stripped automatically). Runtime auto-appendsminsif omitted.
| Key | Action |
|---|---|
enter |
View full JSON details of selected movie |
e |
Edit selected movie |
d |
Delete selected movie (with confirmation) |
c |
Clear all filters and reset to defaults |
ctrl+r |
Refresh the current view |
← / → |
Previous / next page |
Example session:
Movies List (Filters: genres=drama)
ID Title Year Runtime Genres
───────────────────────────────────────────────────────────────────
2 Inglourious Basterds 2009 153 mins adventure, drama, war
1 The Departed 2006 151 mins crime, drama, thriller
Page 1 of 1 (2 records total)
enter: details • esc: back • t/g/y/r/i: search • c: clear • ctrl+r: refresh • d: delete • e: edit • ←/→: page
Press enter on any movie in the list to see the full raw JSON response from GET /v1/movies/:id:
Movie Details (#2)
{
"movie": {
"id": 2,
"title": "Inglourious Basterds",
"year": 2009,
"runtime": "153 mins",
"genres": [
"adventure",
"drama",
"war"
],
"version": 1
}
}
esc: back • ctrl+c: quit
Both forms share the same layout with four fields:
Add New Movie
> Title
Year (e.g. 2024)
Runtime (e.g. "102 mins")
Genres (comma separated)
esc: back • tab: next • enter: submit • ctrl+c: quit
- Add New Movie: All fields start empty. Submitting sends
POST /v1/movies. - Edit Movie: Fields are pre-filled with the current movie data. On submit, you'll see a confirmation prompt:
Are you sure you want to save these changes? (y/n). The edit sendsPATCH /v1/movies/:id.
Runtime formatting: You can enter just the number (e.g.
102) and the client will automatically appendmins.
View the current status of the connected Greenlight API:
Health Check
Status: available
Environment: production
Version: 1.0.0
esc: back • ctrl+c: quit
View your profile and manage your account:
Account Settings
> 1. Reset Password
2. Logout
esc: back • ctrl+c: quit
The project includes a comprehensive Justfile:
| Command | Description |
|---|---|
just run |
Run in development mode |
just build |
Build binary to ./bin/client |
just build-release |
Build optimized binary (stripped symbols) |
just build-linux |
Cross-compile for linux/amd64 |
just test |
Run all tests |
just lint |
Run golangci-lint |
just audit |
Full quality check (tidy, vet, staticcheck, race tests) |
just fmt |
Format all Go code |
just clean |
Remove build artifacts |
greenlight-client/
├── cmd/cli/
│ └── main.go # Application entry point
├── internal/
│ ├── api/
│ │ ├── client.go # HTTP client with auth token management
│ │ ├── auth.go # Login, token handling
│ │ ├── movies.go # Movie CRUD + raw JSON fetching
│ │ ├── users.go # Register, activate, password reset, healthcheck
│ │ └── models.go # Data structures (Movie, Metadata, etc.)
│ └── ui/
│ ├── model.go # Main BubbleTea model & state machine router
│ ├── styles/styles.go # Centralized lipgloss styles
│ ├── set_url.go # API URL input & health verification
│ ├── onboarding.go # Auth menu (login/register/activate/forgot)
│ ├── login.go # Login form
│ ├── register.go # Registration form
│ ├── activate.go # Account activation form
│ ├── forgot_password.go # Password reset request
│ ├── reset_password.go # Password reset with token
│ ├── dashboard.go # Main dashboard menu
│ ├── healthcheck.go # Health check display
│ ├── account_settings.go# Account settings & logout
│ ├── movie_list.go # Movie table with search & pagination
│ ├── movie_detail.go # Raw JSON movie viewer
│ ├── movie_edit.go # Pre-filled movie editor with confirmation
│ └── movie_form.go # New movie creation form
├── Justfile # Build & development commands
├── API_CLIENT_GUIDE.md # Greenlight API reference
└── go.mod