Subject
Complete bv command-line usage reference
Motivation
bv --help is the only usage documentation the CLI has, and help text can only ever be terse: no worked examples, no cross-command workflows, no room for warnings about sharp edges (delegation semantics, the --skip-* escape hatches, exit codes, behavior in CI). The docs/ folder has deep dives on individual subsystems (configuration files, release hooks, directory structure) but no page a user can read to learn to drive bv, and no stable anchor to link from error messages or release notes when a remedy needs longer-form explanation.
Abstract
A hand-written usage reference covering every bv command and global option: purpose, behavior, and interactions (the SDK version check, delegation to the pinned version, configuration resolution order), enriched with usage examples for common workflows, tips 'n' tricks, and alert boxes for pitfalls. Hand-authored by design — the value over --help is precisely the context, examples, and judgment that cannot be generated from command metadata. To keep the page honest without generating it, a test can pin the documented command and option lists against CommandRegistry and the settings types, so that surface drift fails the build instead of silently dating the docs.
Outline
- Introduction: what
bv is; installing and running it (tool manifest, global install, dnx); how delegation picks the version that actually runs
- Global options, each with an example (
--verbosity/-v, --color/--no-color, --nologo, --skip-sdk-check, --skip-delegation, --version)
- The build pipeline (
clean, restore, build, test, pack): the inclusion chain, forwarded arguments (--), configuration resolution
update: what it pins, the upgrade flow, downgrades and --forcerelease: prerequisites, phases, what gets pushed, pointer to release hooksversion show / version advance- Exit codes and Ctrl-C behavior
- Tips 'n' tricks: CI invocations, bisecting an SDK regression with
--skip-sdk-check, running an exact version via dnx
- Troubleshooting: common errors and their remedies (SDK version check failure, home directory not found, multiple configuration files)
- Note on maintenance: hand-written prose, drift-detected by a registry-pinning test
Subject
Complete
bvcommand-line usage referenceMotivation
bv --helpis the only usage documentation the CLI has, and help text can only ever be terse: no worked examples, no cross-command workflows, no room for warnings about sharp edges (delegation semantics, the--skip-*escape hatches, exit codes, behavior in CI). Thedocs/folder has deep dives on individual subsystems (configuration files, release hooks, directory structure) but no page a user can read to learn to drivebv, and no stable anchor to link from error messages or release notes when a remedy needs longer-form explanation.Abstract
A hand-written usage reference covering every
bvcommand and global option: purpose, behavior, and interactions (the SDK version check, delegation to the pinned version, configuration resolution order), enriched with usage examples for common workflows, tips 'n' tricks, and alert boxes for pitfalls. Hand-authored by design — the value over--helpis precisely the context, examples, and judgment that cannot be generated from command metadata. To keep the page honest without generating it, a test can pin the documented command and option lists againstCommandRegistryand the settings types, so that surface drift fails the build instead of silently dating the docs.Outline
bvis; installing and running it (tool manifest, global install,dnx); how delegation picks the version that actually runs--verbosity/-v,--color/--no-color,--nologo,--skip-sdk-check,--skip-delegation,--version)clean,restore,build,test,pack): the inclusion chain, forwarded arguments (--), configuration resolutionupdate: what it pins, the upgrade flow, downgrades and--forcerelease: prerequisites, phases, what gets pushed, pointer to release hooksversion show/version advance--skip-sdk-check, running an exact version viadnx