nils-cli

A Rust workspace of focused CLI binaries for Git operations, API test orchestration, and workflow automation, unified by shared cross-crate helpers.

Workspace layout

Each crate is either a standalone CLI binary or a shared library used across the workspace.

Shared foundations

• crates/nils-common: Shared cross-CLI utilities (small helpers that don’t belong to a specific binary).
• crates/nils-term: Terminal UX helpers (TTY detection + progress rendering on stderr).
• crates/nils-test-support: Test-only helpers for deterministic workspace integration tests.
• crates/cli-template: Minimal example CLI for validating packaging and new-crate patterns.

API testing stack

• crates/api-testing-core: Shared library for the API testing CLIs (config/auth, history, reporting).
• crates/api-rest: REST request runner from JSON request specs, with history + Markdown reports.
• crates/api-gql: GraphQL operation runner for .graphql files (variables, history, reports, schema).
• crates/api-grpc: gRPC request runner from JSON specs, with history + Markdown reports.
• crates/api-websocket: Deterministic WebSocket request runner with history + Markdown reports.
• crates/api-test: Suite runner that orchestrates REST/GraphQL/gRPC/WebSocket cases and outputs JSON (and optional JUnit).

Git tooling

• crates/git-scope: Git change inspector (tracked/staged/unstaged/untracked/commit) with tree + optional file printing.
• crates/git-cli: Git tools dispatcher (utils/reset/commit/branch/ci/open).
• crates/git-summary: Per-author contribution summaries over a date range (adds/dels/net/commits).
• crates/git-lock: Label-based commit locks per repo (lock/list/diff/unlock/tag).

Automation and utility CLIs

• crates/macos-agent: macOS desktop automation primitives for app/window discovery, input actions, screenshot, and wait helpers.
• crates/fzf-cli: Interactive fzf toolbox for files, Git, processes, ports, and shell history.
• crates/memo-cli: Capture-first memo workflow CLI with agent enrichment loop (add, list, search, report, fetch, apply).
• crates/image-processing: Batch image transformation CLI (resize/crop/optimize) with JSON/report outputs.
• crates/screen-record: macOS ScreenCaptureKit + Linux (X11) recorder for a single window or display with optional audio.

Agent and workflow tooling

• crates/agent-docs: Deterministic policy-document resolver for Codex/agent workflows (resolve, contexts, add, baseline).
• crates/codex-cli: Provider-specific CLI for OpenAI/Codex workflows (auth, diagnostics, execution wrappers, Starship), with adapters over nils-common::provider_runtime.
• crates/gemini-cli: Provider-specific CLI lane for Gemini workflows, with adapters over nils-common::provider_runtime.
• crates/semantic-commit: Helper CLI for generating staged context and creating semantic commits.
• crates/plan-tooling: Plan Format v1 tooling CLI (to-json, validate, batches, split-prs, scaffold, completion).
• crates/plan-issue-cli: Plan issue orchestration binaries (plan-issue, plan-issue-local) for task-spec build/start/status/ready/accept/close workflows plus completion export.

Shared helper policy (nils-common)

Contributors should treat nils-common as the shared helper boundary for cross-CLI primitives.

• Put reusable, domain-neutral helpers in crates/nils-common.
• Keep crate-local adapters for user-facing copy, warning style, exit-code mapping, and CLI-specific UX policy.
• During migration, preserve parity by keeping output text/warnings/colors/exit behavior byte-for-byte stable.
• Characterize behavior with tests before moving helper logic, then re-run affected crate tests after migration.

Detailed scope, API examples, migration conventions, and non-goals are documented in crates/nils-common/README.md.

Shell wrappers and completions

Canonical completion architecture and contributor validation live in docs/runbooks/cli-completion-development-standard.md. Use DEVELOPMENT.md for required delivery checks.

Assets:

• completions/zsh/: zsh completions (plus aliases.zsh)
• completions/bash/: bash completions (plus aliases.bash)
• wrappers/: dev-only wrapper scripts
• wrappers/plan-issue-delivery-loop.sh: compatibility wrapper that delegates to plan-issue

Local shell setup:

1. Zsh: add completions/zsh/ to your fpath, then run compinit in your shell init.
2. Zsh (optional): source completions/zsh/aliases.zsh (see completions/zsh/aliases.zsh)
3. Bash: copy completions/bash/<command> into your bash-completion directory, or source them from your shell init.
4. Bash (optional): source completions/bash/aliases.bash (see completions/bash/aliases.bash)
5. Dev-only: add wrappers/ to your PATH (or symlink wrapper scripts into a bin directory).

Contributor checks

Use DEVELOPMENT.md as the canonical checklist.

• Full required checks: ./.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh
• Docs-only fast path: ./.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh --docs-only

Local install (release)

• Build + install all workspace binaries into ~/.local/nils-cli/:
  • ./.agents/skills/nils-cli-install-local-release-binaries/scripts/nils-cli-install-local-release-binaries.sh
• Install only a specific binary:
  • ./.agents/skills/nils-cli-install-local-release-binaries/scripts/nils-cli-install-local-release-binaries.sh --bin git-scope
• Add the install dir to PATH (example):
  • export PATH="$HOME/.local/nils-cli:$PATH"

GitHub Releases (prebuilt binaries)

This repo can publish prebuilt tarballs via GitHub Releases for both:

• x86_64 (amd64)
• aarch64 (arm64)

To trigger a release build, push a tag like v0.5.3:

• git tag -a v0.5.3 -m "v0.5.3"
• git push origin v0.5.3

Then download the matching nils-cli-<tag>-<target>.tar.gz asset, extract it, and add <extract_dir>/bin to your PATH.

Release packaging contract: shipped artifacts must include completions/zsh/, completions/bash/, completions/zsh/aliases.zsh, and completions/bash/aliases.bash. After extracting release assets, follow the same setup flow from "Shell wrappers and completions".

crates.io publishing (shared crates)

Use scripts/publish-crates.sh for crate publishing flow.

• Default list + order: release/crates-io-publish-order.txt
• Dry-run (recommended first):
  • scripts/publish-crates.sh --dry-run
• Real publish:
  • scripts/publish-crates.sh --publish
• Override target crates:
  • scripts/publish-crates.sh --crates "nils-term nils-common" --dry-run

In --dry-run mode, the script runs cargo publish --dry-run for every selected crate. In --publish mode, the script runs dry-run -> publish sequentially per crate (in your specified order). By default, --publish skips crates that are already published at the same version on crates.io.

To query crates.io publish status (single/multi/all crates), use:

• scripts/crates-io-status.sh --all --format text
• scripts/crates-io-status.sh --crates "nils-common nils-codex-cli" --version v0.3.1 --format json
• scripts/crates-io-status.sh --crate nils-codex-cli --format both --json-out "$AGENT_HOME/out/codex-status.json"

--version checks that exact version; without --version the script checks each crate's current workspace version. Use --fail-on-missing for CI gates.

GitHub Actions manual flow is also available at .github/workflows/publish-crates.yml:

• Trigger via workflow_dispatch.
• mode=dry-run runs checks only.
• mode=publish requires repository secret CARGO_REGISTRY_TOKEN.

Adding a new CLI crate

Use the canonical onboarding runbook:

• docs/runbooks/new-cli-crate-development-standard.md