Improve --help output for agent usability

[marc0olo]

Summary

This issue tracks all --help output improvements needed to make icp-cli more usable by agents — particularly those trained primarily on dfx. Poor or missing descriptions cause agents to guess flag formats, hang in interactive prompts, or misidentify commands.

All changes are expected to land in a single PR.

---

1. icp canister settings update — fill in all empty option descriptions

Several flags have completely empty descriptions, making it impossible for an agent to construct a valid call without guessing.

Flag	Add description
--compute-allocation	Compute allocation percentage (0–100). Represents a guaranteed share of a subnet's compute capacity
--log-visibility	Who can read the canister's logs [possible values: controllers, public, allowed-viewers]
--add-log-viewer	Add a principal to the allowed log viewers list
--remove-log-viewer	Remove a principal from the allowed log viewers list
--set-log-viewer	Replace the allowed log viewers list with the specified principals
--add-environment-variable	Add a canister environment variable in KEY=VALUE format
--remove-environment-variable	Remove a canister environment variable by key name

---

2. icp canister settings show — wrong description

Current description says "Show the status of a canister" — identical wording to icp canister status. An agent trying to replicate dfx canister status will be confused about which command to use.

Change to:

Show a canister's configured settings (controllers, compute allocation, memory limits, log visibility, environment variables).

---

3. icp canister status — document no-argument behavior and add examples

The [CANISTER] argument is listed as optional but there is no explanation of what happens when it is omitted. A dfx-trained agent expects dfx canister status --all as an explicit opt-in; here silence means all.

Update the [CANISTER] argument description to add:

If omitted, shows status for all canisters in the environment.

Add an after_long_help examples block (matching the style already used by icp network status):

# Status of all canisters in local environment
icp canister status

# Status of one canister by name
icp canister status backend -e local

# Print only canister IDs (useful for scripting)
icp canister status -i

# JSON output for all canisters
icp canister status --json

---

4. icp network start — document default port and --project-root-override tip

Nothing in the help mentions that the gateway binds to port 8000 by default, that this is configurable, or how to stop a network in another project directory without cd.

Add to the command description or after_long_help:

The gateway binds to port 8000 by default. To use a different port, set gateway.port in icp.yaml. If port 8000 is already in use by another icp-cli project, stop that network first using icp network stop --project-root-override <path>.

---

5. icp new — add non-interactive callout to --silent and --define

Without --define flags, icp new launches an interactive prompt. In CI or automated agent use this hangs silently. Nothing in the current help warns about this.

Update --define description to add:

Required for non-interactive use. Without --define flags, icp new launches an interactive prompt and blocks.

Update --silent description to add:

Use for non-interactive or CI contexts: all variables must be supplied via --define; missing values cause immediate failure instead of prompting.

---

6. icp canister list — document output format

The help says nothing about what the output looks like. An agent scripting against this command has to guess whether it prints names, names + IDs, one per line, etc.

Update command description to:

List the canisters in an environment, showing each canister's name and principal ID. Use --json for machine-readable output.

Add a short example:

# List all canisters with their IDs as JSON
icp canister list --json

---

7. icp environment list — fix typo and add context

Current description: "Display a list of enviroments" — missing the 'n' in "environments".

Also, no explanation of what an environment is relative to a network — important for dfx-migrating agents that have no concept of this distinction.

Change description to:

List the environments defined in this project (name, network, and canisters). Use icp project show to see the fully expanded configuration including implicit environments.

---

8. icp cycles transfer — fill in empty --from-subaccount description

The --from-subaccount flag has no description. All other flags in this command are documented.

Add description:

The subaccount to transfer cycles from