nicely

module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT

README

Nicely

A curated, multilingual CLI toolbox that humans and AI agents operate equally well. The command is ncly.

ncly --help
ncly --version
ncly completion bash

Status

Nicely is in early development. The vision explains what it is and why, and the milestones list the work in order.

The current build implements help, the version, and shell completion. It finds the extensions named ncly-<domain> in ~/.local/share/nicely/extensions/ and in PATH, shows their help and completion from their manifests, starts them with a call that it has checked, checks their JSON answer before passing it on, and stops them and their child processes on Ctrl-C. It also establishes the JSON error contract, configuration, and English message catalog. The commands below are planned work.

Planned commands

Nicely is a small core that every domain extends, in the spirit of Pi. Core brings describe, doctor, auth, run, and tap. It finds extensions named ncly-<domain>, and it bundles one extension, skill, which agents use to learn Nicely. Everything else is an extension, including the first ones: agent, which runs a task through Claude Code, Pi, and other harnesses, and transcript, which transcribes YouTube and Zoom audio and summarizes it through agent. Taps arrive between the two, so transcript installs from the official tap. Everyday domains such as markdown and video, a private docs hub, and Canadian French follow. The domain table records their scope.

Interactive forms will ask for missing values. Scripts and agents set NCLY_NO_INPUT=1 to prevent questions, including in a pseudo-terminal, and use --json or NCLY_JSON=1 for machine output. Commands group actions by domain, such as ncly transcript run youtube.

Planned agent instructions

Once the skill extension ships, one line in your agent instructions will teach an agent to use Nicely:

Before using ncly, run ncly skill view nicely

The bundled nicely skill teaches one loop: find a command with ncly describe, dry-run it when it writes or bills, and, for a recorded command, choose a run ID before the call, so that a lost answer costs nothing. Each error names its cause with a stable code, the exit code says who acts, and, when the hint names a command that runs as is, next holds that command as words. The skill also covers retry safety, inspection, and explicit resume, and each extension ships a skill for its own commands. The agent contract defines the fields and recovery rules. Saved records and verified output files retain work across sessions.

Install

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.fish

These 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.

Privacy

Nicely sends no telemetry. It contacts a service only when a command you run needs it, such as Deepgram for ncly transcript.

Contributing

Issues and pull requests are welcome. AGENTS.md explains how changes are made.

License

MIT. See LICENSE.

Directories

Path Synopsis
cmd
ncly command
Command ncly is Nicely's CLI: core, with its bundled extensions.
Command ncly is Nicely's CLI: core, with its bundled extensions.
internal
cli
Package cli builds the ncly command tree and runs it.
Package cli builds the ncly command tree and runs it.
specdoc
Package specdoc reads the tables of the north-star docs, so that tests can check that the code and the spec agree.
Package specdoc reads the tables of the north-star docs, so that tests can check that the code and the spec agree.
sdk
command
Package command turns command declarations into a command line: the commands and their flags, the global flags, help pages, and printed answers.
Package command turns command declarations into a command line: the commands and their flags, the global flags, help pages, and printed answers.
config
Package config locates Nicely's folders and reads the shared and local config files, as the Configuration section of contract.md defines them.
Package config locates Nicely's folders and reads the shared and local config files, as the Configuration section of contract.md defines them.
contract
Package contract holds the agent contract that every command shares: exit codes, the error registry, answers and their verdict, modes, and command declarations.
Package contract holds the agent contract that every command shares: exit codes, the error registry, answers and their verdict, modes, and command declarations.
extension
Package extension runs a Go extension from one value, as SDK in contract.md defines: started as ncly-<domain>, or compiled into ncly and started by it under that name.
Package extension runs a Go extension from one value, as SDK in contract.md defines: started as ncly-<domain>, or compiled into ncly and started by it under that name.
i18n
Package i18n looks up the text that ncly and its extensions show a human in their message catalogs, and formats numbers, sizes, and dates for the active language.
Package i18n looks up the text that ncly and its extensions show a human in their message catalogs, and formats numbers, sizes, and dates for the active language.
platform
Package platform holds what ncly needs from the operating system: for now, the process tree that cleanup reaches, as Programs that ncly runs in contract.md defines.
Package platform holds what ncly needs from the operating system: for now, the process tree that cleanup reaches, as Programs that ncly runs in contract.md defines.
runner
Package runner runs the programs that ncly and its extensions start, as the Programs that ncly runs section of contract.md defines: their environment, their process group, their cancellation, and their exit code.
Package runner runs the programs that ncly and its extensions start, as the Programs that ncly runs section of contract.md defines: their environment, their process group, their cancellation, and their exit code.
tui
Package tui holds the look that every command shares: the styles, the help page, and the error block.
Package tui holds the look that every command shares: the styles, the help page, and the error block.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL