Skip to content

CLI_REFERENCE.md

Latest commit

 

History

History
56 lines (47 loc) · 6.46 KB

CLI_REFERENCE.md

File metadata and controls

56 lines (47 loc) · 6.46 KB
Raw

CLI Reference

This reference records the actual usage and options reported by the 25 built executables in version 0.1.0. Run a command with the usage shown below. Many tools support -h/--help and -V/--version; a few minimal tools do not expose those switches, so do not assume they are universal.

Command reference

Binary Usage Options / notes
nq-about nq-about [OPTION] -h, --help; -V, --version; --about
nq-doctor nq-doctor [OPTION] -h, --help; -V, --version
nq-hash nq-hash FILE -h, --help; -V, --version. Reads and hashes one file using Core SHA-256.
nq-config-check nq-config-check FILE [--require FIELD]... -h, --help; -V, --version; repeatable --require FIELD. Requires a top-level JSON object.
nq-manifest nq-manifest DIRECTORY -h, --help; -V, --version. Emits a deterministic JSON inventory; one file is buffered at a time.
nq-json-check nq-json-check FILE... or nq-json-check - -h, --help; -V, --version. A single dash reads stdin. Syntax validation only; any JSON value is accepted.
nq-log-view nq-log-view FILE_OR_DASH [FILTER...] --level LEVEL; --contains TEXT; --date YYYY-MM-DD; -h, --help; -V, --version. Filters combine with AND semantics; dash reads stdin.
nq-report nq-report --title TITLE --section NAME=FILE [--section NAME=FILE...] --title is required; repeat --section in output order; -h, --help; -V, --version. Writes Markdown to stdout.
nq-env nq-env [--help] [--version] Reports OS/architecture, selected safe environment values, PATH entry count, and Core metadata. Conservative redaction is not a guarantee that every secret is detected.
nq-diff nq-diff BEFORE.json AFTER.json -h, --help; -V, --version. Inputs are nq-manifest JSON arrays; outputs added, removed, modified, and unchanged entries.
nq-bundle nq-bundle OUTPUT.zip FILE... -h, --help; -V, --version. Stores files by basename and adds nexusq-bundle-manifest.json; refuses duplicate names and existing output.
nq-verify-bundle nq-verify-bundle BUNDLE.zip -h, --help; -V, --version. Verifies entries and hashes without extraction.
nq-workspace nq-workspace list; nq-workspace create rust-cli DIRECTORY; nq-workspace check DIRECTORY list shows templates; create refuses existing destinations; check is read-only.
nq-test-runner nq-test-runner CONFIG.json JSON object with non-empty commands array; each entry requires unique name, non-empty program, optional string-array args. No shell is invoked; this is not a sandbox.
nq-release-notes nq-release-notes CHANGELOG.md [--heading HEADING] --heading selects an exact level-two heading; default is the last level-two section. -h, --help; -V, --version.
nq-doc-audit nq-doc-audit FILE.md... [--require-heading HEADING] Repeat --require-heading; checks relative inline Markdown file links/images and exact required headings. Exit: 0 clean, 1 findings, 2 usage/read error.
nq-cache-report nq-cache-report ROOT... Reports known cache/build directory sizes and counts. Does not delete or clean files. No help/version switches are listed by this binary.
nq-git-audit nq-git-audit [PATH] PATH defaults to current directory. Requires Git and a path inside a repository. Read-only. No help/version switches are listed by this binary.
nq-seal nq-seal OUTPUT.json FILE...; nq-seal --verify MANIFEST.json DIRECTORY --verify; -h, --help; -V, --version. Creates/verifies a hash manifest, not a signature or encryption.
nq-vault nq-vault init VAULT_DIR; add VAULT_DIR FILE...; list VAULT_DIR; verify VAULT_DIR Local content-addressed store with index.json and objects/. No delete, extraction, encryption, or network operation.
nq-sign nq-sign keygen PRIVATE_KEY.txt PUBLIC_KEY.txt; sign PRIVATE_KEY.txt FILE SIGNATURE.json; verify PUBLIC_KEY.txt FILE SIGNATURE.json Ed25519 via Core. Private keys are plaintext hex files; verification trusts only the supplied public key.
nq-policy nq-policy POLICY.json MANIFEST.json Rules: max_files, max_total_size_bytes, allowed_extensions, required_paths. At least one rule is required. Exit: 0 pass, 1 violations, 2 input/usage error.
nq-supply-chain nq-supply-chain Cargo.lock -h, --help; -V, --version. Deterministic local lockfile inventory; no network, package execution, vulnerability database, or publisher authentication.
nq-secure-backup create SOURCE_DIR BACKUP.nqsb --password-file FILE; create SOURCE_DIR BACKUP.nqsb --plain; verify BACKUP.nqsb [--password-file FILE]; restore BACKUP.nqsb NEW_DESTINATION_DIR [--password-file FILE] -h, --help; -V, --version; --password-file; --plain. Encryption is default. Password is never accepted as argv. Restore requires a new destination.
nq-integrate nq-integrate [OPTION] -h, --help; -V, --version. Runs an isolated synthetic Core diagnostic and removes its temporary directory.

Important safety and behavior notes

  • nq-test-runner launches programs directly without a shell but does not sandbox them. Every configured program runs with the user's permissions. Review the JSON before execution.
  • nq-sign private keys are plaintext. Protect the key file and establish trust in public keys independently.
  • nq-vault is not encrypted storage.
  • nq-seal and bundle manifests provide integrity metadata only when the manifest itself is trusted. They are not proof of authorship.
  • nq-policy evaluates manifest metadata and does not inspect artifact contents.
  • nq-supply-chain is not a vulnerability scanner or provenance verifier.
  • nq-secure-backup encrypted mode uses Core Argon2id and AES-256-GCM; --plain removes confidentiality. Archive processing is memory-buffered with a documented 256 MiB limit.
  • nq-cache-report, nq-git-audit, and nq-env report information; they do not clean caches, modify Git state, or change the process environment.

Workspace invocation

From the repository root, use cargo run -p PACKAGE -- ARGS.... Example:

cargo run -p nq-hash -- ./artifact.bin
cargo run -p nq-log-view -- app.log --level ERROR --contains timeout
cargo run -p nq-secure-backup -- create ./project ./project.nqsb --password-file ./backup-password.txt

The published crate and binary names match. Install an individual tool with cargo install PACKAGE; see CRATES_IO.md.