<div align="center">
# RePortal
**Jump between repos. Open in your editor. Stay in sync across machines.**
[](https://crates.io/crates/reportal)
[](https://github.com/CheckPickerUpper/reportal/releases/latest)
[](https://github.com/CheckPickerUpper/homebrew-tap)
[](https://github.com/CheckPickerUpper/scoop-reportal)
[](LICENSE)
[](https://www.rust-lang.org/)
[]()
[]()
</div>
---
RePortal is a single-binary CLI that keeps a registry of your dev repos and lets you fuzzy-jump between them, open them in your editor, and clone missing repos on a new machine.
## Install
All methods install both `reportal` and `rep` (short alias) binaries.
### Cargo (all platforms)
```bash
cargo install reportal
```
### Homebrew (macOS / Linux)
```bash
brew tap CheckPickerUpper/tap
brew install reportal
```
### Scoop (Windows)
```powershell
scoop bucket add reportal https://github.com/CheckPickerUpper/scoop-reportal
scoop install reportal
```
### Winget (Windows)
```powershell
winget install CheckPickerUpper.RePortal
```
### Shell installer (macOS / Linux)
```bash
### PowerShell installer (Windows)
```powershell
### From source
```bash
git clone https://github.com/CheckPickerUpper/reportal.git
cd reportal
cargo install --path .
```
## Quick start
```bash
# Set up config + shell shortcuts (rj, ro)
rep init
# Register a local repo
rep add ~/dev/my-project
# Clone and register from a URL
rep add https://github.com/org/repo.git
# List all registered repos
rep list
# Jump to a repo (cd)
rj
# Open a repo in your editor
ro
```
## Commands
| `rep init` | | Creates config and installs `rj`/`ro` shell shortcuts |
| `rep list` | `rep l` | Shows all repos with path, description, tags, and whether it exists on disk |
| `rep list --tag work` | | Filters repos by tag |
| `rep jump` | `rep j` | Fuzzy-select a repo, prints the path (used by `rj` shell function) |
| `rep jump my-api` | `rep j my-api` | Jump directly to a repo by alias |
| `rep jump --title "Debug"` | | Override the terminal tab title for this session |
| `rep open` | `rep o` | Fuzzy-select a repo, opens it in your editor |
| `rep open my-api` | `rep o my-api` | Opens a repo directly by alias |
| `rep open --editor code` | | Override the default editor |
| `rep open --title "Debug"` | | Override the terminal tab title for this session |
| `rep color` | | Emit tab title + background color for current directory (for shell hooks) |
| `rep color --repo my-api` | | Emit tab title + background color for a specific repo |
| `rep add ~/dev/foo` | `rep a ~/dev/foo` | Register a local repo (auto-detects git remote, suggests alias) |
| `rep add https://github.com/org/repo.git` | | Clone a repo and register it (asks where to place it) |
| `rep remove my-api` | `rep rm my-api` | Unregister a repo (does not delete files) |
## Shell integration
`rep init` automatically installs these shortcuts into your shell profile:
| `rj` | Fuzzy-select a repo and `cd` into it |
| `rj my-api` | Jump directly to a repo by alias |
| `ro` | Fuzzy-select a repo and open it in your editor |
| `ro my-api` | Open a repo directly by alias |
Supports PowerShell, Bash, Zsh. Detected and installed during `rep init`.
You can also set them up manually:
**PowerShell:**
```powershell
function rj { Set-Location (rep jump @args) }
function ro { rep open @args }
```
**Bash / Zsh:**
```bash
rj() { cd "$(rep jump "$@")"; }
ro() { rep open "$@"; }
```
## Config
Lives at `~/.reportal/config.toml`:
```toml
[settings]
default_editor = "cursor"
default_clone_root = "~/dev"
path_on_select = "show" # "show" or "hide" — print path after jump/open
path_display_format = "absolute" # "absolute" or "relative"
[repos.my-api]
path = "~/dev/my-project/api"
description = "Backend API"
tags = ["work", "backend"]
remote = "git@github.com:org/api.git"
title = "API" # custom terminal tab title (defaults to alias)
color = "#1a1a2e" # terminal background color on jump (hex)
[repos.website]
path = "~/dev/personal/site"
description = "Personal website"
tags = ["personal", "frontend"]
```
| `default_editor` | Any command | `cursor` | Editor for `rep open` |
| `default_clone_root` | Any path | `~/dev` | Where `rep add <url>` clones to |
| `path_on_select` | `show`, `hide` | `show` | Print path after picking a repo in jump/open |
| `path_display_format` | `absolute`, `relative` | `absolute` | Full path or relative to current directory |
### Per-repo fields
| `path` | yes | — | Filesystem path to the repo (supports `~`) |
| `description` | no | `""` | Shown in fuzzy finder and `rep list` |
| `tags` | no | `[]` | Filter repos with `--tag` |
| `remote` | no | `""` | Git remote URL for cloning on other machines |
| `title` | no | repo alias | Terminal tab title set via OSC 2 on jump/open |
| `color` | no | reset to default | Terminal background color (`#RRGGBB`) set via OSC 11 on jump/open |
## Terminal personalization
When you jump to or open a repo, RePortal automatically sets:
1. **Tab title** (OSC 2) — uses the `title` config field, falling back to the repo alias
2. **Background color** (OSC 11) — uses the `color` config field; repos without a color reset the terminal to its default
Both sequences go to stderr so they don't interfere with the path output that `rj` captures. Terminals that don't support these sequences silently ignore them.
The `--title` flag on `jump`/`open` lets you override the tab title for a single session without changing config.
### Shell hook for new terminals
Terminals opened directly into a repo (e.g. VS Code integrated terminal) won't go through `rj`, so they won't get the color/title automatically. Add `rep color` to your prompt to fix that:
**PowerShell:**
```powershell
function prompt { rep color 2>$null; "PS> " }
```
**Bash / Zsh:**
```bash
PROMPT_COMMAND='rep color 2>/dev/null'
```
`rep color` matches your current directory against registered repos (longest prefix wins) and emits the right sequences.
## Roadmap
- [x] Config parsing
- [x] `init`, `list`, `jump`, `open`, `add`, `remove`
- [x] Shell integration auto-install (`rj`, `ro`)
- [x] Clone from URL with sibling/child placement
- [x] Auto-detect git remote on `add`
- [x] Colored output with themed fuzzy finder
- [x] `rep` short alias
- [x] Configurable path display (absolute/relative, show/hide)
- [x] Per-repo terminal tab title and background color (OSC 2 / OSC 11)
- [x] `color` command for shell prompt hooks
- [ ] `status` — git status across all repos
- [ ] `sync` — pull latest across repos
- [ ] `dashboard` — rich overview with branches, dirty state, last commit
- [ ] `clone --all` — clone missing repos from config (machine sync)
- [ ] Shell completions
- [ ] Publish to crates.io
## Contributing
PRs welcome. Open an issue first for anything bigger than a typo fix.
## License
[MIT](LICENSE)