A curated, multilingual CLI toolbox that humans and AI agents operate equally well. The command is ncly.
ncly --help
ncly --version
ncly skill view nicely
ncly describe --json
ncly skill list
ncly completion bashNicely is in early development. The vision explains what it is and why, and the backlog queue lists the work in order.
The current build brings:
- Help, the version, shell completion, and
ncly describe, which gives the contract of each installed command - Extensions named
ncly-<slug>, including independent jobs such asncly-video-convert, and the bundledskillextension ncly doctor, which checks the machine, andncly auth, which keeps the keys and their grants- The
agentextension, which runs one trusted task through Codex and records it - The
transcriptextension, which transcribes one YouTube video with Deepgram, records the run, replays it, and stops cleanly on Ctrl-C ncly run listandncly run view, which read the records of the runs- The extension template, which creates an extension repository with its tests and recipes
- SDK checks that explain broken manifest rules and missing catalog IDs in English, with their repository file names
YouTube sign-in refusals stop automatic retries with TRANSCRIPT_DOWNLOAD_FAILED.
Their hint names the transcript browser setting.
Output or key refusals leave no empty run-lock files when --run-id is omitted.
Extension manifests declare errors and warnings with optional command scopes, execution modes, and coverage exemptions linked to issues.
extension.Check rejects invalid scopes with TOML line and column positions.
The test kit requires each declared code in every selected command and mode.
It lists coverage exemptions for the UAT report.
Accepted privacy limits use a declared case, with reads -case '<case>' -limit <id> and an independent reader.
The current build describes each command.
Read the commands and extension workflow.
Add one line to your agent instructions, such as AGENTS.md or CLAUDE.md, to teach an agent to use Nicely:
When asked to use nicely, run ncly skill view nicely
The bundled nicely skill teaches only what this release can do: find a command with ncly describe, dry-run it when it writes or bills, check the machine with ncly doctor when a problem has no explanation, and act on the stable code of each error and on the exit code, which says who acts. When the hint names a command that runs as is, next holds that command as words. An agent reads it before every call, so it stays short and names three bundled skills to read when needed. nicely-auth covers keys and grants, which stay with the human. nicely-runs teaches run IDs that the caller chooses, the inspection of a run with ncly run list and ncly run view, and the verified replay of a completed call. An uncertain paid result never permits an automatic second charge. Explicit resume waits for a workflow that needs it. nicely-extensions teaches how to install, build, and remove an extension. Each extension ships a skill for its own commands, which ncly skill list lists. The agent contract defines the fields and recovery rules.
Install with:
| System | Installation |
|---|---|
| macOS | brew install pascalandy/tap/ncly |
| Linux | Download the archive for your architecture from the releases page |
Homebrew installs the completions for zsh, bash, and fish. On Linux, extract the archive into an empty folder, then put ncly and its completions where your shell finds them:
install -Dm755 ncly ~/.local/bin/ncly
install -Dm644 completions/ncly.bash ~/.local/share/bash-completion/completions/ncly
install -Dm644 completions/_ncly ~/.local/share/zsh/site-functions/_ncly
install -Dm644 completions/ncly.fish ~/.config/fish/completions/ncly.fishThese commands target the default folders: bash also needs the bash-completion package, and with custom XDG folders, use the folders that your shell reads instead. ~/.local/bin must be on your PATH. For zsh, add fpath=(~/.local/share/zsh/site-functions $fpath) to ~/.zshrc before compinit runs.
For a manual setup, ncly completion <shell> --help shows the commands. In bash, load the script with eval "$(ncly completion bash)", because the bash 3.2 of macOS reads nothing from source <(...). The bash script needs the bash-completion package, which Homebrew names bash-completion for bash 3.2 and bash-completion@2 for bash 4.2 and later. In zsh, run eval "$(ncly completion zsh)" after compinit, because the script calls compdef. The redirect into "${fpath[1]}/_ncly" works only when you can write to that folder. Otherwise, use the eval line, or another folder of fpath that you can write to.
From a checkout, with Go and just, run just install. It builds ncly into ~/.local/bin/, or into $XDG_BIN_HOME when that holds an absolute path, as uv tool install does. It builds the first-party extensions, such as agent and transcript, into ~/.local/share/nicely/extensions/, or into $XDG_DATA_HOME/nicely/extensions/ when XDG_DATA_HOME holds an absolute path. To build only some of them, name them: just install agent keeps the installed ncly, and just install ncly agent builds both. A name is ncly, or the folder of a first-party extension in extensions/. An unknown name fails before any build and lists the valid names. The agent extension uses the login of an installed Codex, which ncly doctor agent checks. The transcript extension needs uv and Python 3.12 or later, which ncly doctor transcript checks, with the cookies of Arc when the config selects it.
An external extension, such as ncly-video-convert, installs from its repository at a release tag, with Go and just. Release and install gives the commands, and ncly skill view nicely-extensions gives them to an agent, with the steps that remove an extension.
The host force-stops resistant descendants after 13 seconds, with a nominal two-second reservation for handler cleanup. Force-stop and exit overhead use part of that reservation. Cleanup children can be force-stopped too. An unfinished handler stops at the 15-second deadline and can leave private staging behind. The signal answer then omits the handler's result data.
Nicely sends no telemetry. It contacts a service only when a command you run needs it, such as Deepgram for ncly transcript.
Issues and pull requests are welcome. AGENTS.md explains how changes are made.
On Linux, just verify uses a private D-Bus session and keyring for every step of its scratch run.
It needs dbus-run-session and gnome-keyring-daemon; a missing prerequisite stops the run.
MIT. See LICENSE.