docs: improve --help output for agent usability#492
Open
Conversation
marc0olo
changed the title
Addresses all items from #491, plus one additional gap found during a full help audit: - canister settings update: fill in empty descriptions for --compute-allocation, --log-visibility, --add/remove/set-log-viewer, --add/remove-environment-variable; clarify that --log-visibility only accepts 'controllers'/'public', not 'allowed-viewers' - canister settings show: fix description from "status" to "settings"; fix "enviroment" typo; note no default-to-all behaviour - canister status: document that omitting [CANISTER] queries all canisters in the environment; fix "enviroment" typo; add examples - network start: document default port 8000, gateway.port config, and --project-root-override tip for port conflicts - new: replace misleading template_values_file reference in --silent with accurate non-interactive/CI guidance; improve --define description to mention template-specific variable names and relationship to --silent - canister list: document plain-text and JSON output formats - environment list: fix "enviroments" typo; add context about icp project show - cycles transfer: fix //// comment to /// so --from-subaccount gets a description - cycles mint: document that exactly one of --icp or --cycles is required - docs/reference/cli.md: regenerated
marc0olo
force-pushed
the
fix/help-output-agent-usability
branch
from
bbb4b04 to
e58d2af
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses all items from #491, plus one additional gap found during a full help audit.
Changes
icp canister settings update— fill in all previously empty option descriptions:--compute-allocation: clarify 0–100 percentage range--log-visibility: clarify valid values arecontrollers/publiconly (notallowed-viewers), and point to--add-log-viewer/--set-log-viewerfor per-principal access--add-log-viewer,--remove-log-viewer,--set-log-viewer: add descriptions--add-environment-variable: documentKEY=VALUEformat--remove-environment-variable: document that it takes a key nameicp canister settings show— fix description to accurately state the command shows full canister status (same output asicp canister status), not just configured settings; note that a canister must always be specified; fix "enviroment" typo in argument descriptionicp canister status— document that omitting[CANISTER]queries all canisters in the environment (dfx required--allas explicit opt-in); fix "enviroment" typo in argument description; addafter_long_helpexamples blockicp network start— document the default port (8000), how to configure a different port viagateway.portinicp.yaml, and how to stop a network in another project directory using--project-root-overrideicp new— replace misleadingtemplate_values_filereference in--silent(icp-cli does not expose--template-values-file) with accurate description of non-interactive behaviour; improve--definedescription to mention that variable names are template-specific and that--defineis required in--silentmode for variables with no template defaulticp canister list— document plain-text output (names, one per line) and JSON schema ({"canisters": [...]})icp environment list— fix "enviroments" typo; add context pointing toicp project showfor expanded configurationicp cycles transfer— fix////(plain comment) to///(doc comment) on--from-subaccountso the description appears in--helpicp cycles mint— document that exactly one of--icpor--cyclesis required; previously both appeared fully optional in--helpbut a runtime error was returned if neither was provideddocs/reference/cli.md— regenerated to reflect all the above changes