ICP CLI Usage

Hard rule: no dfx

• Never suggest or use the legacy

  dfx

  command.
• Any time the user mentions

  dfx

  , map the request to the equivalent

  icp

  command(s).
• If a reference or example uses

  dfx

  , translate it to

  icp

  before responding.

Quick start workflow

Default to these steps unless the user asks for a specific command:

1. Create a project:

   icp new my-project

2. Start local network:

   icp network start -d

3. Deploy (builds automatically):

   icp deploy

4. Call a method:

   icp canister call <canister> <method> '(...)'

5. Verify if needed:

   icp network status

   ,

   icp canister status <canister>

Use

-e/--environment

when the user specifies a target (deploy uses environments; network start uses a network name or

-e

).

Non-interactive project creation

icp new

may prompt for template values and can fail in non-TTY contexts. Use explicit template settings to avoid prompts:

icp new my-project --subfolder hello-world \
  --define backend_type=rust \
  --define frontend_type=react \
  --define network_type=Default

Preflight checks

Use these to confirm the environment quickly:

• icp --version

• icp network list

• icp network status

  (or

  icp network ping --wait-healthy

  )

Command map (common tasks)

• Project lifecycle:

  icp new

  ,

  icp build

  ,

  icp deploy

  ,

  icp sync

• Local network:

  icp network start|status|ping|stop

• Canister ops:

  icp canister create|install|call|status|settings

• Identities:

  icp identity new|list|default|principal|import

• Cycles/tokens:

  icp cycles balance|mint|transfer

  ,

  icp token balance|transfer

• Project config:

  icp project show

Decision points

• Local vs mainnet: default to local if unspecified; ask for environment or network if needed.
• Identity: suggest

  --identity

  when multiple identities exist.
• Install mode: use

  --mode install|reinstall|upgrade

  only when user requests it.
• Arguments: if canister call args are unknown, recommend interactive prompt (omit args).
• Network conflicts:

  icp network start

  accepts a network name or

  -e

  ;

  icp deploy

  uses

  -e

  (no

  -n

  flag).
• Environment variables: mention

  ICP_ENVIRONMENT

  when the user wants a default.

Usage guidance (from README)

• Default to local network workflows unless a target is specified.
• Use

  -e/--environment

  or

  -n/--network

  when a target is named, but never both.
• Suggest

  --identity

  when multiple identities might exist.
• Provide the minimal command set plus a short verify step.
• If call arguments are unknown, omit args to trigger the interactive prompt.

Troubleshooting local network

• Port 8000 already in use: local PocketIC binds to

  localhost:8000

  . If

  icp network start

  fails, check and stop the other process with

  lsof -i :8000

  and

  kill <PID>

  .
• Shutdown:

  icp network stop

  (use when finished with local testing).
• Verify network:

  icp network status

  or

  icp network ping --wait-healthy

Tool calls

Use tool calls to validate the latest CLI help and documentation.

CLI help (preferred when available locally):

{ "tool": "Shell", "command": "icp --help" }

{ "tool": "Shell", "command": "icp canister --help" }

{ "tool": "Shell", "command": "icp network --help" }

Docs pages (when the CLI isn’t available or for citations):

{
  "tool": "WebFetch",
  "url": "https://dfinity.github.io/icp-cli/reference/cli/"
}

{
  "tool": "WebFetch",
  "url": "https://dfinity.github.io/icp-cli/guides/local-development/"
}

{
  "tool": "WebFetch",
  "url": "https://dfinity.github.io/icp-cli/guides/installation/"
}

Repo context (for changes or deeper details):

{ "tool": "WebFetch", "url": "https://github.com/dfinity/icp-cli" }

Responses

When replying to users:

• Provide the smallest set of commands to accomplish the task.
• Include flags only when necessary to meet the user’s environment or identity needs.
• Offer a short "verify" step (e.g.,

  icp network status

  ,

  icp canister status

  ).
• Cite official docs or the CLI help when explaining flags or behavior.
• Ask for missing details only when required: environment/network, canister name, method, and args.

Self-test prompts

Use these to sanity-check outputs:

• "Start a local network and deploy" → quick start workflow + verify step.
• "Call a canister method but I don't know args" → omit args to trigger prompt.
• "Deploy to staging" → use

  -e staging

  , avoid

  -n

  .
• "Check cycles and top up" →

  icp cycles balance

  +

  icp canister top-up

  .

Examples

Create and deploy a project locally

Commands:

icp new hello-icp
cd hello-icp
icp network start -d
icp network status
icp deploy
icp canister call backend greet '("World")'

Create a project non-interactively (CI/non-TTY)

Commands:

icp new hello-icp --subfolder hello-world \
  --define backend_type=rust \
  --define frontend_type=react \
  --define network_type=Default
cd hello-icp
icp network start -d
icp deploy

Check cycles and top up

Commands:

icp cycles balance
icp canister top-up --amount 2t backend

Deploy to a named environment

Commands:

icp deploy -e staging
icp canister status -e staging

Sources

• https://dfinity.github.io/icp-cli/
• https://dfinity.github.io/icp-cli/reference/cli/
• https://dfinity.github.io/icp-cli/guides/local-development/
• https://dfinity.github.io/icp-cli/guides/installation/
• https://github.com/dfinity/icp-cli