{"id":51204341,"url":"https://github.com/tui-cs/clet","last_synced_at":"2026-06-28T02:07:54.403Z","repository":{"id":355664734,"uuid":"1228998007","full_name":"tui-cs/clet","owner":"tui-cs","description":"CLIs for prompting with rich TUI, mouse/keyboard, typed inputs, consistent JSON output and exit codes.","archived":false,"fork":false,"pushed_at":"2026-06-23T17:04:01.000Z","size":5904,"stargazers_count":7,"open_issues_count":8,"forks_count":3,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-06-23T17:34:18.191Z","etag":null,"topics":["bat","cli","command-line","dialog","glow","gum","linux","macos","markdown","markdown-viewer","terminal","terminal-ui","tui"],"latest_commit_sha":null,"homepage":"","language":"C#","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/tui-cs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-05-04T15:40:23.000Z","updated_at":"2026-06-23T17:04:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tui-cs/clet","commit_stats":null,"previous_names":["gui-cs/clet","tui-cs/clet"],"tags_count":95,"template":false,"template_full_name":null,"purl":"pkg:github/tui-cs/clet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tui-cs%2Fclet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tui-cs%2Fclet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tui-cs%2Fclet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tui-cs%2Fclet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tui-cs","download_url":"https://codeload.github.com/tui-cs/clet/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tui-cs%2Fclet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34874576,"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-28T02:00:05.809Z","response_time":54,"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":["bat","cli","command-line","dialog","glow","gum","linux","macos","markdown","markdown-viewer","terminal","terminal-ui","tui"],"created_at":"2026-06-28T02:07:54.290Z","updated_at":"2026-06-28T02:07:54.395Z","avatar_url":"https://github.com/tui-cs.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"![clet hero](docs/images/hero.png)\n\n**One binary. Every prompt. JSON out. Go home.**\n\nA `clet` is a CLI-let - Simple CLI commands that prompt the user with rich TUI (full mouse/keyboard), typed inputs, consistent JSON output and exit codes.\n\nWorks for humans and AI agents alike.\n\n## Available Clets\n\n| Alias | Description | Options |\n| --- | --- | --- |\n| `select` | Presents a list of options and returns the text of the selected item. | `--options`, `args...` |\n| `text`, `multiline-text`, `mt` | Prompts for multi-line text input using an editor and returns the entered string. | |\n| `int` | Prompts for an integer value using a numeric spinner. | `--step` |\n| `decimal` | Prompts for a decimal value using a numeric spinner. | `--step` |\n| `confirm` | Prompts for a yes/no confirmation and returns a boolean. | |\n| `date` | Prompts for a date and returns an ISO-8601 date string (YYYY-MM-DD). | |\n| `time` | Prompts for a time and returns an ISO-8601 time string (HH:MM:SS). | |\n| `duration` | Prompts for a duration and returns an ISO-8601 duration string (e.g. PT1H30M). | |\n| `color` | Prompts for a color and returns a hex string (#rrggbb). | |\n| `multi-select` | Presents a list of options with checkboxes and returns the selected texts. | `--options`, `args...` |\n| `attribute-picker`, `attribute` | Prompts for text attributes (foreground, background, style) and returns a JSON object. | |\n| `pick-file`, `file` | Opens a file picker dialog and returns the selected file path(s). | `--multi`, `--root`, `--filter` |\n| `pick-directory`, `dir` | Opens a directory picker dialog and returns the selected directory path. | `--root` |\n| `linear-range`, `range` | Presents a linear range selector (single, multi, or bounded range) over labelled options. | `--mode`, `--options`, `--range-kind`, `args...` |\n| `md`, `markdown` | Browse and render Markdown files with link navigation and syntax highlighting. | `--theme`, `--cat`, `--no-browse`, `args...` |\n| `edit`, `editor` | Opens a full-screen text editor for files or piped content. | `args...` |\n| `config` | Edit the clet configuration file (`~/.tui/clet.config.json`). | |\n\n## Install\n\n### Release (not available until v1.0 is released)\n\n```sh\nbrew install tui-cs/tap/clet  # macOS / Linux\nwinget install tui-cs.clet    # Windows 10/11\ndotnet tool install -g clet   # any platform with .NET SDK\n```\n\n### Pre-Release\n\n```sh\ndotnet tool install -g clet --prerelease\n```\n\n\u003e **Upgrading from a `-develop` build?** Develop prereleases are no longer published to NuGet. If you previously installed a `-develop` version, clear the NuGet cache before reinstalling:\n\u003e ```sh\n\u003e dotnet tool uninstall -g clet\n\u003e dotnet nuget locals http-cache --clear\n\u003e dotnet tool install -g clet --prerelease\n\u003e ```\n\n\u003e **zsh/bash users:** If `clet` isn't found after `dotnet tool install`, add the tools directory to your PATH:\n\u003e ```sh\n\u003e echo 'export PATH=\"$HOME/.dotnet/tools:$PATH\"' \u003e\u003e ~/.zshrc  # or ~/.bashrc\n\u003e source ~/.zshrc\n\u003e ```\n\u003e PowerShell does this automatically; zsh and bash do not.\n\n### Native binaries (direct download)\n\nStandalone NativeAOT binaries (no .NET runtime required) are available for macOS, Linux, and Windows. See [full install instructions](#native-binaries-install) at the bottom of this file.\n\n## What it replaces\n\n| Task | Before `clet` | With `clet` |\n|---|---|---|\n| Prompt for a choice | `select` / `gum choose` / `fzf` | `clet select \"prod\" \"staging\" \"dev\"` |\n| Pick a file | `gum file` (fuzzy filter) | `clet pick-file` (real tree dialog) |\n| Confirm an action | `read -p \"Sure? [y/N]\"` | `clet confirm \"Deploy to prod?\"` |\n| Render Markdown | `glow` / `bat` / `mdcat` | `clet md ./CHANGELOG.md` |\n| Quick text editing | `nano` / `vi` / `micro` | `clet edit ./notes.txt` |\n| Multiple tools, mismatched exit codes | `read` + `dialog` + `fzf` + `glow` | `clet` — one tool, one contract |\n\n## Usage\n\n### Human usage\n\n```sh\n# Pick from a list\nclet select \"prod\" \"staging\" \"dev\"\n\n# Pick a file from a tree dialog\nclet pick-file --root ./src --title \"Choose a source file\"\n\n# Confirm before a destructive action\nclet confirm \"This will delete 40k rows. Continue?\"\n\n# Render a Markdown file — full-screen, dismiss with q / Esc\nclet md ./CHANGELOG.md\n\n# Edit a file in the built-in editor\nclet edit ./notes.txt\n\n# Open the configuration editor (theming, keybindings, etc.)\nclet config\n\n# See available commands (TUI help viewer)\nclet help\n```\n\n### AI agent usage (`--json`)\n\n```sh\n# Structured elicitation — agent gets a typed result, not raw text\nclet select --json \"prod\" \"staging\" \"dev\"\n# → {\"schemaVersion\":1,\"status\":\"ok\",\"value\":\"staging\"}\n\n# Pick a file with a timeout\nclet pick-file --json --root ./src --timeout 30s\n# → {\"schemaVersion\":1,\"status\":\"ok\",\"value\":\"src/User.ts\"}\n\n# Confirm an action\nclet confirm --json \"Apply this patch?\"\n# → {\"schemaVersion\":1,\"status\":\"cancelled\"}   (exit 130)\n\n# Discover available commands (machine-readable manifest)\nclet --opencli\n# → {\"name\":\"clet\",\"version\":\"...\",\"commands\":[{\"alias\":\"select\",\"kind\":\"input\",\"resultType\":\"string\",...},...]}\n```\n\nExit codes: \n\n- `0` success\n- `2` usage error\n- `130` cancelled (SIGINT convention).\n\n### Demos\n\n**`clet help`**\n\n![clet help](./docs/images/clet-help.gif)\n\n**`clet pick-file`**\n\n![clet pick-file](./docs/images/clet-pick-file.gif)\n\n**`clet color`**\n\n![clet color](./docs/images/clet-color.gif)\n\n\n## RC feedback\n\nclet is in **release candidate** status ([milestone tracker](https://github.com/tui-cs/clet/issues/33)). If something doesn't work, looks wrong, or is just confusing, **[file an issue](https://github.com/tui-cs/clet/issues/new)**. Include:\n\n- `clet --version` output (e.g. `1.0.0-rc.3 (Terminal.Gui 2.0.2-develop.37)`).\n- Your terminal + OS (e.g. \"Windows Terminal on Windows 11\", \"iTerm2 on macOS 15\").\n- What you ran, what you expected, what happened.\n\n## FAQ\n\n### Q: Why not just use `gum` (or `glow`, or `bat`, or `dialog`)?\n\nEach of those is good at one thing. `clet` is the unification, with a real UI toolkit underneath. Every clet has full mouse support, configurable keybindings, themed colors, and one consistent navigation model. `clet pick-file` is Terminal.Gui's `FileDialog` — a real tree with sortable columns, extension filters, and breadcrumbs, not a fuzzy-filter over `find` output. And because inputs and viewers live in one tool, you get the same keys and colors whether you're picking a file or reading a Markdown document.\n\nFor a shell user who only needs `read`-with-validation, `gum` is fine. We are not competing for that user.\n\n### Q: What's the difference between an input clet and a viewer clet?\n\n- **Input clets** (`select`, `text`, `pick-file`, …) prompt for a value and return a typed result: exit 0, `{\"schemaVersion\":1,\"status\":\"ok\",\"value\":…}`.\n- **Browser clets** (`md`) render content with link navigation, back/forward history, and return on dismiss: exit 0, `{\"schemaVersion\":1,\"status\":\"ok\"}`.\n\nBoth share theming, keybindings, mouse support, and the JSON envelope.\n\n### Q: What does the JSON output look like?\n\n```json\n{ \"schemaVersion\": 1, \"status\": \"ok\",      \"value\": \"prod\" }   // input selected\n{ \"schemaVersion\": 1, \"status\": \"ok\" }                         // viewer dismissed\n{ \"schemaVersion\": 1, \"status\": \"cancelled\" }                  // Esc / Ctrl-C (exit 130)\n{ \"schemaVersion\": 1, \"status\": \"error\", \"code\": \"validation\", \"message\": \"…\" }\n```\n\n### Q: Exit codes?\n\n- `0` success\n- `1` no-result\n- `2` usage error\n- `130` cancelled (SIGINT convention).\n\n### Q: Cancellation and timeouts?\n\nEsc and Ctrl-C cancel input clets; `q`, Esc, and Ctrl-C dismiss viewer clets. `--timeout \u003cduration\u003e` (e.g. `--timeout 30s`) cancels automatically — useful for AI agent scripts.\n\n### Q: Which clets ship in v1.0?\n\n**Input (14):** `text`, `int`, `decimal`, `select`, `multi-select`, `confirm`, `pick-file`, `pick-directory`, `date`, `time`, `duration`, `color`, `attribute-picker`, `linear-range`\n\n**Viewer (4):** `md` (Markdown browser with link navigation, back/forward history, and syntax highlighting), `edit` (full-screen text editor), `config` (configuration editor for `~/.tui/clet.config.json`), `help`\n\nRun `clet list` to see what's available in your installed version.\n\n### Q: Theming?\n\nEvery clet inherits the active Terminal.Gui theme automatically. To customize, create `~/.tui/clet.config.json`:\n\n```json\n{\n  \"Theme\": \"MyTheme\",\n  \"Themes\": {\n    \"MyTheme\": {\n      \"ColorSchemes\": {\n        \"Base\": {\n          \"Normal\":    { \"Foreground\": \"#E0E0E0\", \"Background\": \"#1E1E1E\" },\n          \"Focus\":     { \"Foreground\": \"#FFFFFF\", \"Background\": \"#264F78\" },\n          \"HotNormal\": { \"Foreground\": \"#569CD6\", \"Background\": \"#1E1E1E\" },\n          \"HotFocus\":  { \"Foreground\": \"#9CDCFE\", \"Background\": \"#264F78\" }\n        }\n      }\n    }\n  }\n}\n```\n\nOr, you can pick from a built-in Terminal.Gui Theme. This example picks the `Anders` theme, a nod to [Anders Heilsberg](https://www.microsoft.com/en-us/behind-the-tech/anders-hejlsberg-a-craftsman-of-computer-language) who created TurboPascal. \n\n```json\n{\n  \"Theme\": \"Anders\"\n}\n```\n\n\u003cimg width=\"576\" height=\"131\" alt=\"image\" src=\"https://github.com/user-attachments/assets/df36bca2-25b5-4904-af51-5a9de9e9be35\" /\u003e\n\nHere's `clet color` with the Anders theme applied:\n\n![clet color with Anders theme](./docs/images/clet-color.gif)\n\nAll clets render with the `Base` color scheme, so customizing `Base` controls every clet's appearance. See the [Terminal.Gui Configuration docs](https://tui-cs.github.io/Terminal.Gui/docs/configuration.html) for the full schema.\n\n### Q: Key bindings?\n\nKey bindings are also configured via `~/.tui/clet.config.json`:\n\n```json\n{\n  \"Key.Bindings\": {\n    \"Application.QuitKey\": \"Ctrl+Q\"\n  }\n}\n```\n\nThis changes the quit/dismiss key for all clets. `clet md` shows the active quit key in the status bar automatically.\n\n### Q: Do I need .NET installed?\n\n**No** - for `brew install`, `winget install`, and the [direct-download native binaries](#native-binaries-install) on the GitHub Releases page — all three ship a self-contained NativeAOT binary (~8 MB, no runtime needed). The direct-download binaries are *not yet code-signed*; the `brew` and `winget` channels stay signed.\n\n**Yes** - for `dotnet tool install -g clet`.\n\n### Q: What's the `--prerelease` channel?\n\nReleases from `main` publish prerelease packages to NuGet (versioned `1.x.y-rc.N` during the RC phase). Stable users see no churn — `dotnet tool install -g clet` still resolves to the latest non-prerelease, and `brew`/`winget` only ship stable main releases. If you want the bleeding edge, pass `--prerelease`.\n\n### Q: How do I report a bug or give feedback?\n\n[File an issue](https://github.com/tui-cs/clet/issues/new). That's the only feedback channel — no Discussions, no forum. See the [RC feedback](#rc-feedback) section above for what to include.\n\n## Native binaries install\n\nEvery [GitHub release](https://github.com/tui-cs/clet/releases) ships standalone NativeAOT binaries for the three primary platforms. **No .NET runtime required** — single-file executable, ~20 MB, cold-start in tens of milliseconds.\n\n| Platform | Asset |\n|---|---|\n| macOS (Apple Silicon) | `clet-\u003cversion\u003e-osx-arm64.tar.gz` |\n| Linux x64 | `clet-\u003cversion\u003e-linux-x64.tar.gz` |\n| Windows x64 | `clet-\u003cversion\u003e-win-x64.zip` |\n\n\u003e **Not yet code-signed.** Apple/Windows code signing is deferred until after v1.0. macOS Gatekeeper will quarantine the binary on first run, and Windows SmartScreen may warn. If you don't want to bypass those prompts, use `brew` / `winget` / `dotnet tool install` instead — those channels stay signed.\n\n**macOS (Apple Silicon):**\n```sh\n# Replace \u003cversion\u003e with the release tag, e.g. 1.0.0-develop.41\ncurl -LO https://github.com/tui-cs/clet/releases/latest/download/clet-\u003cversion\u003e-osx-arm64.tar.gz\ntar -xzf clet-\u003cversion\u003e-osx-arm64.tar.gz\nxattr -d com.apple.quarantine ./clet  # clear Gatekeeper quarantine\nsudo mv clet /usr/local/bin/\nclet --version\n```\n\n**Linux x64:**\n```sh\ncurl -LO https://github.com/tui-cs/clet/releases/latest/download/clet-\u003cversion\u003e-linux-x64.tar.gz\ntar -xzf clet-\u003cversion\u003e-linux-x64.tar.gz\nchmod +x ./clet\nsudo mv clet /usr/local/bin/\nclet --version\n```\n\n**Windows x64 (PowerShell):**\n```powershell\n# Replace \u003cversion\u003e with the release tag\nInvoke-WebRequest -Uri \"https://github.com/tui-cs/clet/releases/latest/download/clet-\u003cversion\u003e-win-x64.zip\" -OutFile clet.zip\nExpand-Archive clet.zip -DestinationPath $env:USERPROFILE\\bin\\clet\n# Add $env:USERPROFILE\\bin\\clet to your PATH, then:\nclet --version\n```\n\nIf SmartScreen blocks the download, click **More info → Run anyway**, or unblock the file with `Unblock-File .\\clet.exe`.\n\n### About `libonigwrap`\n\nEach archive includes a native library (`libonigwrap.dylib` on macOS, `libonigwrap.so` on Linux, `onigwrap.dll` on Windows). This is the [Oniguruma](https://github.com/kkos/oniguruma) regex engine used by TextMateSharp for **syntax highlighting in code blocks** when viewing Markdown (`clet md`).\n\nThe `clet` binary runs fine without it — everything works except syntax highlighting in fenced code blocks will be plain text. If you want syntax highlighting, keep the library in the same directory as the `clet` binary. On macOS, clear its quarantine flag too:\n\n```sh\nxattr -d com.apple.quarantine ./libonigwrap.dylib\n```\n\n## Further reading\n\n- [Demo scripts](demos/README.md) — runnable examples showing how to chain clets in scripts\n- [Press release \u0026 customer voices](specs/press-release.md)\n- [Implementation spec](specs/clet-spec.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftui-cs%2Fclet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftui-cs%2Fclet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftui-cs%2Fclet/lists"}