nicely

module
v0.27.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 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 skill view nicely
ncly describe --json
ncly skill list
ncly completion bash

Status

Nicely 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 as ncly-video-convert, and the bundled skill extension
  • ncly doctor, which checks the machine, and ncly auth, which keeps the keys and their grants
  • The agent extension, which runs one trusted task through Codex and records it
  • The transcript extension, which transcribes one YouTube video with Deepgram, records the run, replays it, and stops cleanly on Ctrl-C
  • ncly run list and ncly 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.

Commands and extensions

Read the commands and extension workflow.

Let your agent find it

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

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.

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.

Cancellation

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.

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.

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.

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.
extensions
agent
Package agent is the external extension that runs one trusted task through Codex, as extensions/agent/spec.md defines.
Package agent is the external extension that runs one trusted task through Codex, as extensions/agent/spec.md defines.
agent/cmd/ncly-agent command
Command ncly-agent runs the agent extension as an external extension.
Command ncly-agent runs the agent extension as an external extension.
skill
Package skill is the bundled extension that lists the skills that teach agents, as extensions/skill/spec.md defines.
Package skill is the bundled extension that lists the skills that teach agents, as extensions/skill/spec.md defines.
transcript
Package transcript is the external extension that transcribes one YouTube video with Deepgram, as extensions/transcript/spec.md defines.
Package transcript is the external extension that transcribes one YouTube video with Deepgram, as extensions/transcript/spec.md defines.
transcript/cmd/ncly-transcript command
Command ncly-transcript runs the transcript extension as an external extension.
Command ncly-transcript runs the transcript extension as an external extension.
internal
cli
Package cli builds the ncly command tree and runs it.
Package cli builds the ncly command tree and runs it.
keychain
Package keychain keeps keys in the OS keychain, as Keys in contract.md defines.
Package keychain keeps keys in the OS keychain, as Keys in contract.md defines.
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
analysis
Package analysis holds the Go analyzers of the SDK and runs them through go vet -vettool, as Analyzers in contract.md defines.
Package analysis holds the Go analyzers of the SDK and runs them through go vet -vettool, as Analyzers in contract.md defines.
analysis/callerenv
Package callerenv refuses whole caller environment reads in the test kit, repository gates, TLC runner and their child packages.
Package callerenv refuses whole caller environment reads in the test kit, repository gates, TLC runner and their child packages.
analysis/cmd/nicelyvet command
Command nicelyvet runs the analyzers of the SDK for go vet -vettool.
Command nicelyvet runs the analyzers of the SDK for go vet -vettool.
analysis/runnerdiscard
Package runnerdiscard refuses io.Discard as the Stdout or Stderr of a runner.Program, as Analyzers in contract.md defines.
Package runnerdiscard refuses io.Discard as the Stdout or Stderr of a runner.Program, as Analyzers in contract.md defines.
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.
Package extension runs a Go extension from one value, as SDK in contract.md defines.
extensionrepo
Package extensionrepo runs repository tasks through the extension's export program.
Package extensionrepo runs repository tasks through the extension's export program.
extensionrepo/cmd/extensionrepo command
Command extensionrepo runs repository tasks through the shared SDK, including from a downloaded Nicely module.
Command extensionrepo runs repository tasks through the shared SDK, including from a downloaded Nicely module.
extensionrepo/test command
Command test runs Go tests and prints their collected notices after the package results.
Command test runs Go tests and prints their collected notices after the package results.
extensiontest
Package extensiontest is the test kit of an extension repository, as Test kit in contract.md defines.
Package extensiontest is the test kit of an extension repository, as Test kit in contract.md defines.
extensiontest/fake command
Command fake is the fake child of the test kit.
Command fake is the fake child of the test kit.
extensiontest/guard command
Command guard runs one call of a scenario for the test kit, which builds it from this source, as it builds the fake child.
Command guard runs one call of a scenario for the test kit, which builds it from this source, as it builds the fake child.
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: the process tree that cleanup reaches, as Programs that ncly runs in contract.md defines, and the durable writes and the locks of the files in the state folder, as Record format defines.
Package platform holds what ncly needs from the operating system: the process tree that cleanup reaches, as Programs that ncly runs in contract.md defines, and the durable writes and the locks of the files in the state folder, as Record format defines.
record
Package record keeps the records of recorded operations, as Operations in contract.md defines them: run IDs, one durable record per run, the lock that one execution holds, the transitions of its steps, and the verified artifacts that a success answers from.
Package record keeps the records of recorded operations, as Operations in contract.md defines them: run IDs, one durable record per run, the lock that one execution holds, the transitions of its steps, and the verified artifacts that a success answers from.
runner
Package runner runs the programs that ncly and its extensions start, as the Programs that ncly runs section of contract.md defines.
Package runner runs the programs that ncly and its extensions start, as the Programs that ncly runs section of contract.md defines.
tui
Package tui holds the look that every command shares: the styles, the help page, the error block, the masked field of a key, and the confirmation.
Package tui holds the look that every command shares: the styles, the help page, the error block, the masked field of a key, and the confirmation.
verification
Package verification runs the TLA+ models of a repository with a pinned TLC, as Formal models in the contract defines (COR-104-T8).
Package verification runs the TLA+ models of a repository with a pinned TLC, as Formal models in the contract defines (COR-104-T8).
wrap
Package wrap runs one program for a handler, such as a worker, as Wrapped programs in contract.md defines.
Package wrap runs one program for a handler, such as a worker, as Wrapped programs in contract.md defines.

Jump to

Keyboard shortcuts

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