Lantern use cases

This guide focuses on real workflows. For the full command reference, see docs/commands.md.

Interactive TUI Mode

Lantern provides a full interactive TUI (terminal user interface) powered by the dialog CLI. This is ideal for users who prefer menu-driven interfaces over remembering command-line flags.

Launching TUI Mode

lantern
lantern --tui
lantern -t

TUI Workflow: First-Time Setup

1. Launch TUI: lantern (or lantern --tui)
2. Configure servers: Select config > setup
3. Add a server: Choose from presets (github.com, gitlab.com, bitbucket.org) or add a custom server
4. Enter credentials: Provide your username and optionally your API token
5. Save: Select "Save and exit" to write the configuration
6. Set workspace root: Go to config > workspace and set your workspace path (e.g., ~/workspace)
7. Set scan JSON path (optional): Go to config > scan_path

Now all repository operations will use your configured root directory automatically.

TUI Workflow: Daily Usage

Once configured, a typical session looks like:

1. Launch TUI: lantern (or lantern --tui)
2. Open dashboard: Select dashboard to build one fleet snapshot and inspect repos row-by-row
3. Review dirty repos: Select dirty_repos before signing off to find tracked local changes quickly
4. Reconcile repos: From the dashboard repo action menu, refresh local, publish local, or checkout the latest branch
5. Deep inspect a repo: Use Review local changes to open the selected repository in lazygit
6. Find a repo: Select find and enter a name filter to locate a specific repo
7. Exit: Select exit (screen is cleared automatically)

TUI Workflow: Cloning from a Git Server

1. Launch TUI: lantern (or lantern --tui)
2. Clone repos: Select forge > "Clone repositories from list"
3. Auto list handling: Lantern auto-uses an existing repo-list JSON, or auto-generates it if missing
4. Choose clone directory: Defaults to your session root
5. Select repos: Use the checklist to pick which repos to clone
6. Clone destination: Repos are cloned into namespace directories by default, so my-namespace/my-repo becomes my-namespace/my-repo under your workspace root. Choose the flat layout when you explicitly want the repository cloned directly into the root as my-repo.

TUI Workflow: Interactive Server Setup

The lantern config setup command (also accessible via TUI config > setup) provides a wizard for server management:

Server Configuration
├── Add a new server
│   ├── github.com (preset)
│   ├── gitlab.com (preset)
│   ├── bitbucket.org (preset)
│   └── custom (enter hostname, provider, base URL)
├── Edit existing server (change username/token)
├── Remove a server
├── Set default server
├── Save and exit
└── Exit without saving

Adding a custom self-hosted server:

1. Select "Add a new server" > "custom"
2. Enter hostname (e.g., gitlab.mycompany.com)
3. Select provider type (github/gitlab/bitbucket)
4. Enter API base URL (e.g., https://gitlab.mycompany.com/api/v4)
5. Enter your username
6. Optionally add your API token (entered securely, not echoed)

TUI Features

• Session-based root directory: Set once, used for all operations in the session
• Scrollable output: Large tables are displayed in scrollable text boxes
• Clean exit: Screen is cleared when exiting
• Non-destructive config editing: Server changes are only saved when you explicitly choose "Save and exit"
• Secure token entry: Tokens are entered via password fields (not visible on screen)

Installing dialog

The TUI requires the dialog CLI:

# Debian/Ubuntu
sudo apt install dialog

# macOS
brew install dialog

# Fedora/RHEL
sudo dnf install dialog

# Arch Linux
sudo pacman -S dialog

Server config (GitHub, GitLab, Bitbucket)

Lantern loads server settings from JSON config. Use a per-user config file: - ~/.git-lantern/config.json (preferred) - ~/.config/git-lantern/config.json

You can also set GIT_LANTERN_CONFIG=/path/to/config.json.

Example config:

{
  "default_server": "github.com",
  "servers": {
    "github.com": {
      "provider": "github",
      "base_url": "https://api.github.com",
      "USER": "my-user",
      "TOKEN": "ghp_xxx",
      "organizations": [
        { "name": "my-org-a", "token": "ghp_org_a_token" },
        { "name": "my-org-b" }
      ]
    },
    "gitlab.com": {
      "provider": "gitlab",
      "base_url": "https://gitlab.com/api/v4",
      "USER": "my-user",
      "TOKEN": "glpat_xxx"
    },
    "bitbucket.org": {
      "provider": "bitbucket",
      "base_url": "https://api.bitbucket.org/2.0",
      "USER": "my-user",
      "TOKEN": "bb-token",
      "auth": { "type": "bearer" }
    }
  }
}

Show the active config path:

lantern config path

Export/import server config (for moving settings between machines):

lantern config export --output git-lantern-servers.json
lantern config import --input git-lantern-servers.json
lantern config import --input git-lantern-servers.json --replace

Local repo status and sync

Unified fleet workflow (recommended)

Use fleet as the single command family for multi-repo management: - detect local-vs-remote differences, - clone missing repos, - pull repos that are behind, - optionally push repos that are ahead.

# 1) Build the primary dashboard snapshot (from workspace root)
lantern fleet overview --root ~/workspace --server github.com --fetch
lantern fleet overview --root ~/workspace --server github.com --fetch --with-prs
lantern fleet overview --root ~/workspace --server github.com --fetch --output data/fleet-snapshots/latest.json

# 2) Apply actionable changes from a saved snapshot
lantern fleet apply --root ~/workspace --snapshot data/fleet-snapshots/latest.json --clone-missing --pull-behind

# 3) Apply all actionable changes with live refresh
lantern fleet apply --root ~/workspace --server github.com --clone-missing --pull-behind --push-ahead --only-clean

# 4) Apply without pushing ahead repos
lantern fleet apply --root ~/workspace --server github.com --clone-missing --pull-behind --only-clean

# 5) Apply only selected repos
lantern fleet apply --root ~/workspace --server github.com --repos repo1,repo2 --clone-missing --pull-behind --push-ahead

# 6) Refresh only repos with actionable latest-branch updates
lantern fleet apply --root ~/workspace --server github.com --checkout-latest-branch --clone-missing

# 7) Refresh the latest branches for an explicit repo subset
lantern fleet apply --root ~/workspace --server github.com --checkout-latest-branch --repos repo1,repo2

# 8) Show tracked local changes only
lantern fleet dirty --root ~/workspace

# 9) Dry run with full JSON report
lantern fleet apply --root ~/workspace --server github.com --dry-run --log-json data/fleet-logs/run.json

# 10) Inspect latest report with jq pretty output
lantern fleet logs --latest

In TUI (lantern --tui): 1. select dashboard 2. choose server 3. decide whether to refresh refs and include PR data 4. select a repo row from the dashboard 5. choose Refresh local, Checkout latest branch, Publish local, Review local changes, or Show path 6. for dirty worktrees, use Review local changes to jump directly into lazygit 7. use dirty_repos when you only want repos with tracked local modifications

Latest-branch refresh behavior: - Lantern auto-selects repos whose detected latest branch is actionable: different from the current branch, or behind on that same latest branch. Missing-local repos join that set when --clone-missing is enabled. - You can still narrow or override the scope with --repos or the TUI checklist. In TUI latest-refresh selection, actionable repos are prechecked but you can add or remove repos before apply. - Latest-branch checkout skips tracked uncommitted changes, but untracked-only files do not block the checkout.

For full CLI parity inside TUI, use command and enter any lantern args directly.

lantern repos

List local repos with minimal metadata.

lantern repos --root ~/workspace

lantern scan

Create a JSON snapshot of all repos.

lantern scan --root ~/workspace --output data/repos.json --fetch

lantern status

Live table of repo status.

lantern status --root ~/workspace --fetch
lantern status --root ~/workspace --fetch --with-prs

lantern fleet overview

Primary fleet dashboard snapshot.

lantern fleet overview --root ~/workspace --server github.com --fetch
lantern fleet overview --root ~/workspace --server github.com --fetch --with-prs
lantern fleet overview --root ~/workspace --server github.com --fetch --output data/fleet-snapshots/latest.json

lantern fleet dirty

Tracked local changes only.

lantern fleet dirty --root ~/workspace

lantern lazygit

Open lazygit for a repository discovered under root.

# interactive selection with dialog
lantern lazygit --root ~/workspace --select

# by name under root
lantern lazygit --root ~/workspace --repo git-lantern

# explicit path
lantern lazygit --path ~/workspace/git-lantern

lantern table

Render a table from a JSON scan.

lantern table --input data/repos.json
lantern table --input data/repos.json --columns name,branch,up_ahead,up_behind

lantern find

Find repos by name or remote URL.

lantern find --root ~/workspace --name lantern
lantern find --root ~/workspace --remote gitlab.com

lantern duplicates

Find duplicated clones that share the same origin URL.

lantern duplicates --root ~/workspace

lantern sync

Fetch/pull/push across repos.

lantern sync --root ~/workspace --fetch
lantern sync --root ~/workspace --pull --only-clean --only-upstream
lantern sync --root ~/workspace --push --only-clean

lantern report

Export scan data to CSV/JSON/Markdown.

lantern report --input data/repos.json --output data/repos.csv
lantern report --input data/repos.json --output data/repos.md --format md

GitHub / GitLab / Bitbucket repos (forge)

The forge commands pull repo lists from your configured servers and can clone missing repos to a workspace. These are useful for keeping a multi-host workspace in sync.

List repos from a server

Omit --output to render a table instead of JSON.

lantern forge list --server github.com --output data/github.json
lantern forge list --server gitlab.com --output data/gitlab.json
lantern forge list --server bitbucket.org --output data/bitbucket.json
lantern forge list --server github.com --org my-org-a --org my-org-b --output data/github-orgs.json
lantern forge list --server github.com --all-orgs --with-user --output data/github-all.json

Clone missing repos to a workspace

lantern forge clone --server github.com --input data/github.json --root ~/workspace
lantern forge clone --server gitlab.com --input data/gitlab.json --root ~/workspace
lantern forge clone --server bitbucket.org --input data/bitbucket.json --root ~/workspace

Check status or pull after cloning

lantern status --root ~/workspace --fetch
lantern sync --root ~/workspace --pull --only-clean --only-upstream

Gists and snippets

Lantern supports: - GitHub gists (via lantern forge gists). - GitHub/GitLab/Bitbucket snippets (via lantern forge snippets).

List gists (GitHub)

Omit --output to render a table instead of JSON.

lantern forge gists list --server github.com --output data/gists.json

Download gist files (GitHub)

lantern forge gists clone GIST_ID --input data/gists.json --output-dir ./gists
lantern forge gists clone GIST_ID --file readme.md --output-dir ./gists

Update a gist (GitHub)

lantern forge gists update GIST_ID --file ./notes.txt --force
lantern forge gists update GIST_ID --file readme.md=./README.md
lantern forge gists update GIST_ID --delete old.txt --force

Create a gist (GitHub)

lantern forge gists create --file ./notes.txt --description "Notes" --public
lantern forge gists create --file ./notes.txt --description "Notes" --private

List snippets (GitHub/GitLab/Bitbucket)

Omit --output to render a table instead of JSON.

lantern forge snippets list --server github.com --output data/snippets.json
lantern forge snippets list --server gitlab.com --output data/snippets.json
lantern forge snippets list --server bitbucket.org --output data/snippets.json

Download snippet files (GitHub/GitLab/Bitbucket)

lantern forge snippets clone SNIPPET_ID --input data/snippets.json --output-dir ./snippets
lantern forge snippets clone SNIPPET_ID --file README.md --output-dir ./snippets

Update or create a snippet (GitHub only)

lantern forge snippets update SNIPPET_ID --file ./notes.txt --force
lantern forge snippets update SNIPPET_ID --delete old.txt --force
lantern forge snippets create --file ./notes.txt --description "Notes" --public
lantern forge snippets create --file ./notes.txt --description "Notes" --private

GitLab/Bitbucket: list and clone only (create/update not yet implemented).