/docs/cli-examples
This is a task-oriented companion to iicp-node --help. Every example is designed for copying, but you should still read the command and replace sample names, URLs, models, and limits before running it.
Set up the CLI, inspect its local state, and diagnose a saved node before changing anything.
Confirm which release is on your PATH and read its built-in command reference.
iicp-node --version
iicp-node --helpExpected: The CLI prints its release and the commands supported by that exact binary.
Run the interactive setup wizard and save a reusable node configuration.
iicp-node initExpected: The wizard stores operator and node configuration under the IICP home directory.
Note: Review every value before accepting it. Secret material must not be copied into tickets, logs, or shared configuration files.
Find saved node names, then inspect one without starting a provider.
iicp-node list
iicp-node doctor --node my-node
iicp-node doctor --node my-node --jsonExpected: Doctor reports local configuration, backend, directory, and recovery findings. The JSON form is suitable for scripts.
Submit a conversational task. Directory discovery does not receive the prompt, but the selected executor does.
Discover an eligible chat provider and print its response.
iicp-node query "Explain IICP in one sentence."Expected: The client discovers a route, submits the task to the selected provider, and prints the response.
Note: Do not submit confidential material unless the selected execution path and your policy permit it.
Require the sensitive routing profile and bound response length and waiting time.
iicp-node query "Summarise this non-secret text." \
+ --routing-profile sensitive \
+ --max-tokens 256 \
+ --timeout-ms 90000Expected: The client fails closed if the profile cannot be satisfied and stops waiting after the caller timeout.
Query a directory selected by the operator instead of the public default.
iicp-node query "Hello from my trust domain." \
+ --directory-url https://directory.example.test/apiExpected: Only the configured directory is contacted for discovery.
Note: Finding a directory is not the same as trusting it. Use the identity and trust configuration required by your deployment.
Expose only a backend and model you intend to make available. Start locally before adding a public endpoint.
Start a node created by the setup wizard.
iicp-node serve --node my-nodeExpected: The node loads its saved configuration, registers where configured, and begins serving and heartbeating.
Expose one local model through the default OpenAI-compatible backend path.
iicp-node serve \
+ --model qwen2.5:0.5b \
+ --backend-url http://localhost:11434Expected: The node advertises the configured chat service and forwards accepted tasks to the local backend.
Select an explicitly supported backend interface.
# vLLM
iicp-node serve --model my-model --backend-type vllm --backend-url http://127.0.0.1:8000
# llama.cpp
iicp-node serve --model my-model --backend-type llamacpp --backend-url http://127.0.0.1:8080Expected: The node uses the selected adapter while advertising the effective service it can expose end to end.
Start without public discovery or federation dependencies.
iicp-node serve --node my-local-node --mode local_onlyExpected: The runtime applies the saved local-only configuration.
Note: Validate the projected configuration first. Restricted-mode enforcement is being completed across all peer, gossip, relay, and CIP paths during Beta.
Use explicit health, configuration, proxy, MCP, credit, and supervisor interfaces instead of inferring state from process presence.
Read the node's explicit liveness and readiness snapshot.
iicp-node healthcheck --node my-nodeExpected: The command reports runtime health for the selected saved node.
Check a configuration file before using it to start a node.
iicp-node config validate --file iicp-node.jsonExpected: Invalid combinations fail before the runtime is started.
Expose a loopback OpenAI/Ollama/Anthropic-compatible gateway for existing applications.
iicp-node proxy --host 127.0.0.1 --port 9483Expected: The compatibility API listens on loopback and routes through IICP.
Note: Keep the proxy on loopback unless you have deliberately added authentication and network policy.
Read the selected node's ledger and verify signed award evidence.
iicp-node credits --node my-node
iicp-node credits --node my-node --verifyExpected: The first command prints the balance; the second audits awards against the signed log.
Expose an explicitly approved local MCP server as an IICP provider.
iicp-node mcp-gateway --helpExpected: The CLI prints the gateway options supported by the installed release.
Note: Start with help because transport, tool allowlists, and execution policy are deployment-specific. Tool generation does not imply permission to execute tools.
Generate or install the operating-system service supported by the current CLI.
iicp-node service --helpExpected: The CLI shows the available launchd, systemd, or platform-specific actions.
Note: Inspect generated service definitions before installing them. Service supervision does not prove backend or network readiness.
Use these guides for installation, reachability, privacy boundaries, errors, and configuration context.