{"id":50910916,"url":"https://github.com/nihildigit/shulker","last_synced_at":"2026-06-16T10:01:27.873Z","repository":{"id":355024218,"uuid":"1225852904","full_name":"NihilDigit/shulker","owner":"NihilDigit","description":"Cross-platform TUI for a friend-group Minecraft Paper/Purpur server.","archived":false,"fork":false,"pushed_at":"2026-05-01T17:28:39.000Z","size":445,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T18:29:50.838Z","etag":null,"topics":["minecraft","paper","purpur","rust","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NihilDigit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T17:57:07.000Z","updated_at":"2026-05-01T17:28:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NihilDigit/shulker","commit_stats":null,"previous_names":["nihildigit/mc-tui","nihildigit/shulker"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/NihilDigit/shulker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NihilDigit%2Fshulker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NihilDigit%2Fshulker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NihilDigit%2Fshulker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NihilDigit%2Fshulker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NihilDigit","download_url":"https://codeload.github.com/NihilDigit/shulker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NihilDigit%2Fshulker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34400456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["minecraft","paper","purpur","rust","tui"],"created_at":"2026-06-16T10:01:26.648Z","updated_at":"2026-06-16T10:01:27.866Z","avatar_url":"https://github.com/NihilDigit.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shulker\n\n[![Test](https://github.com/NihilDigit/shulker/actions/workflows/test.yml/badge.svg)](https://github.com/NihilDigit/shulker/actions/workflows/test.yml)\n[![Release](https://img.shields.io/github/v/release/NihilDigit/shulker?display_name=tag)](https://github.com/NihilDigit/shulker/releases/latest)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\nA small TUI (terminal UI) manager for a local Minecraft Paper / Purpur server.\n\n`shulker` manages the boring parts of running a friend-group MC server without leaving the terminal — switching worlds, editing whitelist / ops / `server.properties` / `paper-global.yml`, scheduling daily restarts and backups, pre-generating chunks, watching the live log, and bringing tunnels up/down through SakuraFrp.\n\nIt's intentionally a thin layer over the same files Paper / Purpur already write. Stop using `shulker` at any time and your server keeps working.\n\n## Install\n\n### One-line install (recommended)\n\n```bash\n# Linux / macOS\ncurl -fsSL https://raw.githubusercontent.com/NihilDigit/shulker/main/scripts/install.sh | sh\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/NihilDigit/shulker/main/scripts/install.ps1 | iex\n```\n\nThe script detects your platform, fetches the latest release, and drops `shulker` into `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\\shulker` (Windows). Override the install dir with `SHULKER_INSTALL_DIR=...`; pin a version with `SHULKER_VERSION=v1.0.0`. (The legacy `MC_TUI_INSTALL_DIR` / `MC_TUI_VERSION` names still work as fallbacks.)\n\n### Pre-built binaries (manual)\n\nGitHub Releases ship binaries for Linux / macOS / Windows on x86_64 and aarch64. Download the archive for your platform, extract, run.\n\n### From source\n\n```bash\ncargo install --git https://github.com/NihilDigit/shulker\n```\n\n### Platform notes\n\n- **Linux:** install `tmux` from your distro's package manager (`pacman -S tmux` / `apt install tmux`).\n- **macOS:** install `tmux` via Homebrew (`brew install tmux`). Config dir is `~/Library/Application Support/shulker/` (per Apple's HIG).\n- **Windows:** **closing shulker stops the Minecraft server** — there's no `tmux attach`-style detach on Windows. Drive the server through the in-app Overview tab + Logs overlay. Config dir is `%APPDATA%\\shulker\\`.\n\n## Quickstart\n\nFirst-time setup, end-to-end:\n\n```bash\n# 1. Scaffold a fresh server (detects Java, fetches the jar, writes eula + start script).\nshulker new ~/mc-server\n\n# 2. Open the TUI against it. Subsequent runs remember the last --server-dir.\nshulker --server-dir ~/mc-server\n\n# 3. Inside the TUI: press S to start, ? for the complete key legend, q to quit.\n```\n\n`shulker new` flags: `--server-type paper|purpur` (default purpur), `--mc-version 1.21.4` (default: latest), `--first-boot` (run the server once to generate `server.properties`), `--force` (allow non-empty target dir).\n\nIf you already have a server directory, skip step 1.\n\n## Usage\n\n```bash\nshulker --server-dir /path/to/server\n# or via env var\nMC_SERVER_DIR=/path/to/server shulker\n# without either, shulker uses the last server-dir it remembers.\nshulker\n```\n\nThe directory must contain `server.properties`. `whitelist.json` and `ops.json` are created on demand.\n\n## Tabs\n\nFive top-level views:\n\n- **1 Overview** — server status, recent activity, world / player snapshot, join-address bar, server-lifecycle actions.\n- **2 Players** — unified roster from `whitelist.json` ∪ `ops.json` ∪ `world/playerdata/*.dat` ∪ rolling log corpus. Names rejected with \"not whitelisted\" surface a `denied YYYY-MM-DD` marker.\n- **3 Worlds** — list every world, see which is current, switch the active level by writing `level-name`.\n- **4 Settings** — file picker into `server.properties` and every Paper / Purpur YAML. Right-side detail panel shows default + range + restart-required + bilingual description.\n- **5 Network** — SakuraFrp account + tunnel list live from `api.natfrp.com/v4`; manage tunnels and shulker's directly-managed `frpc` subprocess. Always-visible NIC list (collapsed by default).\n\nThe **join-address bar** is always visible between the status row and the tab bar — click the chip to copy `\u003cip\u003e:\u003cport\u003e` to the system clipboard.\n\n## Keys\n\n`?` opens the in-app help overlay with the complete legend. The essentials:\n\n### Global\n\n| Key | Action |\n|---|---|\n| `1` … `5` | Jump to tab |\n| `Tab` / `Shift+Tab` | Cycle tabs |\n| `↑` / `↓` | Move selection |\n| `Enter` | Confirm / activate selection |\n| `Esc` | Close overlay; back out of sub-views |\n| `S` / `X` / `R` | Start / stop / restart the server |\n| `B` | Run `backup.sh` now |\n| `L` | Open fullscreen log overlay |\n| `Y` | Copy share-text to clipboard |\n| `?` | Help overlay |\n| `:` | Command palette (schedule, pre-gen chunks, attach, scheduler paths) |\n| `D` | Switch `--server-dir` at runtime |\n| `T` | Toggle 中 / EN |\n| `r` | Refresh from disk (and SakuraFrp API on Network) |\n| `q` | Quit |\n\n### Players tab\n\n| Key | Action |\n|---|---|\n| `Enter` | Toggle whitelist |\n| `o` | Toggle op for selected player |\n| `←` / `→` | Cycle op level (1↔4, wraps) |\n| `d` | Purge from whitelist + ops |\n| `a` | Add player (whitelist-add prompt) |\n| `w` | Toggle the `white-list` setting |\n\n### Worlds tab\n\n| Key | Action |\n|---|---|\n| `Enter` | Switch active world (refuses while server is running) |\n| `N` | New world (writes `level-name`; server generates the dir on next start) |\n\n### Network tab\n\n| Key | Action |\n|---|---|\n| `Enter` | Copy tunnel public address |\n| `t` | Set SakuraFrp API token |\n| `i` | One-key setup wizard |\n| `c` / `m` / `d` | Create / migrate / delete tunnel |\n| `e` / `x` | Enable / disable selected tunnel (frpc subprocess) |\n| `o` | Open natfrp.com in browser |\n| `A` | Manual SakuraFrp address override |\n| `n` | Toggle the NIC list |\n\n### Logs overlay\n\n| Key | Action |\n|---|---|\n| `↑` / `↓` | Scroll |\n| `PgUp` / `PgDn` / `Home` / `End` | Page / boundary scroll |\n| `Esc` | Close |\n\n**Mouse:** click tab bar, list rows, or the join chip (chip → clipboard).\n**In a prompt:** type the value, `Enter` to confirm, `Esc` to cancel.\n\n## Configuration\n\nshulker stores state in your OS-native config dir (Linux `~/.config/shulker/`, macOS `~/Library/Application Support/shulker/`, Windows `%APPDATA%\\shulker\\`):\n\n- `state.toml` — last-used `--server-dir`, language, SakuraFrp manual address override, frpc enabled tunnel ids.\n- `natfrp.token` (mode `0600`) — SakuraFrp API token; set via `t` on the Network tab. Never written to logs or `state.toml`.\n- `frpc` — the SakuraFrp `frpc` binary, downloaded on demand by the one-key setup wizard (`i` on Network).\n\nDelete any of these to reset the corresponding state — shulker recreates them as needed.\n\n## See also\n\nDeveloper / agent documentation (architecture, module layout, behavior contracts, contribution style) lives in [`CLAUDE.md`](CLAUDE.md). `AGENTS.md` is a symlink to the same file.\n\n## License\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnihildigit%2Fshulker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnihildigit%2Fshulker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnihildigit%2Fshulker/lists"}