CLI Reference & Commands

PILSO OS is controlled through a lightweight, Node-based CLI interface. You can use the CLI to:

• Start and manage agent sessions

• Interact with roles and configs

• Debug sessions and tool calls

• Run MCP tools directly

Below is a full reference of available commands and options.

---

Core Commands

---

npx pilso

Launch the CLI in interactive mode.

• Prompts you to initialize or select a config

• Automatically creates .pilso directory on first run

• Launches the default agent interface

---

npx pilso start [-r <role>]

Starts a new session using the specified role.

npx pilso start -r signer

• Loads agent personality from pilso-roles.json

• Connects to configured LLM

• Displays live prompt interface

Flags:

• -r, --role → Specify which role to use

• --log → Enable session logging

• --trace → Show full prompt/tool execution trace

---

npx pilso call --tool <tool.method> --args <json>

Run an MCP tool directly without using the LLM agent.

npx pilso call --tool erc20.transfer --args '{"to": "0x123...", "amount": "100", "token": "USDC"}'

• Useful for debugging tools or writing scripted workflows

• Expects valid JSON input

• Returns raw output from the MCP server

---

npx pilso config

Manage your core config file.

npx pilso config view

→ View the current pilso.config.json

npx pilso config edit

→ Opens the config in your default code editor

npx pilso config reset

→ Resets to default configuration template

---

npx pilso roles

Manage agent roles.

npx pilso roles list

→ View all roles in pilso-roles.json

npx pilso roles view <name>

→ View details of a specific role

npx pilso roles add <name>

→ Create a new role via interactive prompt

npx pilso roles edit <name>

→ Edit a role in your editor

---

npx pilso sessions

List and manage past sessions.

npx pilso sessions list

→ List all session logs by timestamp or ID

npx pilso sessions view <id>

→ Open a past session and replay logs

---

CLI Flags (Global)

Flag	Description
--role, -r	Specify which agent role to use
--log	Enable session logging
--trace	Show all internal tool calls and responses
--silent	Suppress most CLI output (for scripting)

---

Development Usage

You can build tooling around the CLI, including:

• Automating workflows with shell scripts

• Calling MCP tools programmatically

• Wrapping pilso call for frontends or dApps

Example:

npx pilso call --tool chainlist.getRPC --args '{"chain": "optimism"}'

---

Tips

• Use --trace during development to inspect full LLM ↔ MCP ↔ Wallet flow

• Use pilso call to test tool servers directly without launching a session

• Keep roles narrow — don't overload a single agent with unrelated tasks

• Use session logs to debug unexpected agent behavior

---

Output Directory

All session artifacts and logs are stored under:

.pilso/
├── pilso.config.json
├── pilso-roles.json
├── session-logs/

Each session log is stored as a full .json file with:

• Prompt history

• Tool usage

• Model output

• Transaction payloads