nicely

module
v0.18.3 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 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 milestones list the work in order.

The current build brings:

  • Help, the version, shell completion, and ncly describe, which gives the contract of each installed command
  • The extensions named ncly-<domain>, which it finds, checks, and stops, 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 the repository of an extension outside Nicely, with its tests and its recipes

The current build describes each command. 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, and run. It bundles skill, which agents use to learn Nicely. Other domains use external extensions named ncly-<domain>.

The first agent command runs one trusted task through Codex. The first transcript command transcribes one explicitly selected YouTube video. A checkout installs the extensions with just install. Each capability starts with its smallest useful path; additional harnesses, transcript summaries, and taps remain in M99.

The plan also keeps an everyday task chosen from real use, a local view of selected project docs, and Canadian French. Markdown is the first everyday candidate. The domain table records their scope.

In a terminal, a form asks a human for each missing value. 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.

Agent instructions

Add one line to your agent instructions, such as AGENTS.md or CLAUDE.md, to teach an agent to use Nicely:

Before using ncly, 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. Each extension ships a skill for its own commands, which ncly skill list lists. It 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. 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.

From a checkout, with Go and just, run just install. It builds ncly into ~/.local/bin/ and 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. 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.

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