# 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.

```bash
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.

```bash
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:

```bash
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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pil.so/cli-reference-and-commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.