# IBM Paver CLI command reference

The IBM® Paver command-line interface (CLI) provides capabilities for interacting with Paver directly from your terminal. You can use the Paver CLI to run automated tasks, start interactive chat sessions, manage conversations and settings, and configure skills and credentials.

For commands used inside the interactive chat session, see [IBM Paver chat commands reference](https://paver.ibm.com/docs/tui-reference.md).

## Prerequisites

Complete the following steps to install the Paver CLI:

1. Install the Paver CLI by running the following command on MacOS or Linux:

   ```text
   curl -fsSL https://paver.cloud.ibm.com/cli/install | bash
   ```

2. Log in with your IBM Cloud® account credentials by running `paver login`. For more information, see [`paver login`](#paver-login). If you don't have an IBM Cloud account, you can [create an account](https://cloud.ibm.com/registration).

For more information about installing the CLI or instructions for Windows, see [Installing the IBM Paver CLI](https://cloud.ibm.com/docs/paver?topic=paver-paver-cli-install). To keep the CLI up to date, see [`paver update`](#paver-update).

## paver ask

Send a single message to Paver, stream the response to your terminal, and exit without opening an interactive session. Use this command in scripts, CI/CD pipelines, or other AI automation, where you can combine it with `--json` for machine-readable output and `--guard` to control approvals when no one is available to respond.

```text
paver ask PROMPT [--continue] [-c, --conversation CONVERSATION_ID] [--json] [--verbose] [--skill SKILL_NAME] [--guard POLICY] [--no-color]
```

### paver ask options

| Option                               | Description                                                                                                                           |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `PROMPT`                             | The message to send to Paver. Required. Enclose the prompt in quotation marks if it contains spaces.                                  |
| `--continue`                         | Continue from the most recent conversation. If Paver responds with a question, use this option and enter your answer as the `PROMPT`. |
| `-c, --conversation CONVERSATION_ID` | Continue a specific conversation by ID.                                                                                               |
| `--json`                             | Return the response as JSON.                                                                                                          |
| `--verbose`                          | Show detailed information such as tool calls, reasoning, and time spent on the task.                                                  |
| `--skill SKILL_NAME`                 | Preload and invoke a specific skill for this request.                                                                                 |
| `--guard POLICY`                     | Set the Paver Guard policy for this request. This option overrides your configuration. See the following list for valid values.       |
| `--no-color`                         | Disable colored output.                                                                                                               |

Valid `POLICY` values for the `--guard` option:

| Policy                | Behavior                                                                                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto-approve-low`    | Low-risk operations run automatically. Medium and high-risk operations prompt for `y/n` approval.                                                                                                                         |
| `auto-approve-medium` | Low and medium-risk operations run automatically. Only high-risk operations require manual approval.                                                                                                                      |
| `auto-deny-medium`    | Paver automatically denies its first attempt at a medium or high-risk operation and tries another approach. If Paver can't find another approach after several attempts, it asks you for permission to run the operation. |
| `auto-deny-high`      | Paver automatically denies its first attempt at a high-risk operation and tries another approach. If Paver can't find another approach after several attempts, it asks you for permission to run the operation.           |
| `todo smart`          | Auto-approve to-do list status updates, but require approval for add and delete.                                                                                                                                          |
| `todo true`           | Auto-approve all to-do list operations.                                                                                                                                                                                   |
| `todo false`          | Require approval for all to-do list operations.                                                                                                                                                                           |
| `no-auto-approval`    | Requires approval for all operations.                                                                                                                                                                                     |
| `reset`               | Restore the default guard rules to auto-approve low-risk operations.                                                                                                                                                      |

For more information about approval policies, see [Managing safeguards and controls in Paver](https://paver.ibm.com/docs/core-concepts/managing-risk-and-control.md).

### paver ask examples

List all VPCs in the `eu-de` region.

```text
paver ask "list all VPCs in eu-de"
```

Continue from your most recent conversation to run a Terraform plan.

```text
paver ask "run terraform plan" --continue
```

Return the response as JSON so that another tool or script can parse it.

```text
paver ask "why is my app failing?" --json
```

## paver chat

Start an interactive chat session, which is a full-screen terminal application that streams responses, renders markdown, and supports slash commands. Use this command when you want to work through a task conversationally, review proposed actions, and approve changes as Paver goes. For information about slash commands and interactive features, see [IBM Paver chat commands reference](https://paver.ibm.com/docs/tui-reference.md). For information about how safe mode and edit mode work, see [Safety mode](https://paver.ibm.com/docs/core-concepts/managing-risk-and-control.md#safety-mode).

```text
paver chat [--continue] [-c, --conversation CONVERSATION_ID] [-v, --verbose] [--guard POLICY] [--no-color] [--no-stream]
```

Running `paver` with no subcommand starts `paver chat`.

### paver chat options

| Option                               | Description                                                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--continue`                         | Resume the most recent conversation.                                                                                                                         |
| `-c, --conversation CONVERSATION_ID` | Resume a specific conversation by ID.                                                                                                                        |
| `-v, --verbose`                      | Show detailed information such as tool calls, reasoning, and time spent on the task.                                                                         |
| `--guard POLICY`                     | Set the Paver Guard policy for this session only. This option overrides your configuration. For valid values, see [`paver ask` options](#paver-ask-options). |
| `--no-color`                         | Disable colored output.                                                                                                                                      |

### paver chat examples

Start a new session.

```text
paver chat
```

Resume the most recent conversation.

```text
paver chat --continue
```

Resume a specific conversation by ID.

```text
paver chat -c CONVERSATION_ID
```

Start a session with a session-scoped Paver Guard policy that allows low-risk operations to run automatically and includes detailed output.

```text
paver chat --guard auto-approve-low --verbose
```

## paver config

Get, set, list, or reset CLI configuration values. Configuration is stored in `~/.paver/config.json` and is never overwritten when you update the CLI. To override a value for a single invocation instead, use the `--config` [global option](#global-options).

```text
paver config (list | get KEY | set KEY VALUE | reset -y)
```

### paver config subcommands

| Subcommand        | Description                                                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `list`            | Show all configuration keys and values. Aliases: `ls`, `show`.                                                                            |
| `get KEY`         | Get the value of a specific configuration key.                                                                                            |
| `set KEY VALUE`   | Set the value of a configuration key. `VALUE` is parsed as JSON when possible, such as `true` or `5`. Otherwise, it's stored as a string. |
| `reset -y, --yes` | Reset all configuration values to their defaults. The `-y` option is required to confirm. If you omit it, the command makes no changes.   |

### paver config examples

Show all configuration values.

```text
paver config list
```

Disable automatic update checks by setting a configuration value.

```text
paver config set update.auto_detect false
```

## paver conversation

Alias: `paver conv`

List and manage your past conversations. Use this command to review a previous conversation, resume it in chat mode, export it, or delete conversations that you no longer need.

```text
paver conversation (list | new [TITLE] | show CONVERSATION_ID | todos CONVERSATION_ID | resume CONVERSATION_ID | remove CONVERSATION_ID | export CONVERSATION_ID [--format FORMAT] [-o, --output FILE] | clear) [--json] [-y, --yes] [-f, --force]
```

### paver conversation subcommands

| Subcommand               | Description                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `list`                   | List all past conversations. Alias: `ls`.                                                            |
| `new [TITLE]`            | Create a new conversation. If not specified, the default title is `New Conversation`.                |
| `show CONVERSATION_ID`   | Show a specific conversation.                                                                        |
| `todos CONVERSATION_ID`  | Show the todo list for a conversation.                                                               |
| `resume CONVERSATION_ID` | Resume a conversation in chat mode. `CONVERSATION_ID` can also be the number from the `list` output. |
| `remove CONVERSATION_ID` | Permanently delete a conversation. Alias: `rm`.                                                      |
| `export CONVERSATION_ID` | Export a conversation. By default, the export is JSON.                                               |
| `clear`                  | Delete all conversations.                                                                            |

### paver conversation options

| Option                     | Description                                                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--json`                   | Output the result as JSON. Accepted by `list`, `new`, `show`, `todos`, and `resume`.                                          |
| `--format FORMAT`          | The export format. Valid values are `json` and `markdown`. If not specified, the default value is `json`. Used with `export`. |
| `-o, --output FILE`        | The file to export the conversation to. If not specified, the export is printed to standard output. Used with `export`.       |
| `-y, --yes`, `-f, --force` | Skip the confirmation prompt. `remove` and `clear` prompt for confirmation by default.                                        |

### paver conversation examples

List all past conversations as JSON.

```text
paver conversation list --json
```

Export a conversation as a Markdown file.

```text
paver conversation export CONVERSATION_ID --format markdown --output conversation.md
```

Delete a conversation without a confirmation prompt.

```text
paver conversation remove CONVERSATION_ID -y
```

## paver feedback

Submit and manage feedback about Paver. The `/feedback` slash command inside `paver chat` is a common way to submit feedback.

```text
paver feedback (list | create TEXT)
```

### paver feedback subcommands

| Subcommand    | Description                                                                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list`        | List all feedback. Alias: `ls`.                                                                                                                                   |
| `create TEXT` | Submit new feedback. The feedback is associated with your most recent conversation, when available, and Paver attempts to attach your most recent local log file. |

### paver feedback examples

Submit feedback.

```text
paver feedback create "The conversation export is missing tool calls"
```

## paver files

Alias: `paver file`

Manage files in the sandbox workspace. For information about how Paver uses workspace files, see [Sharing files with Paver](https://paver.ibm.com/docs/core-concepts/files.md).

```text
paver files (list | upload PATH [REMOTE_NAME] | download NAME [LOCAL_PATH] | remove NAME | clear) [--json] [-y, --yes] [-f, --force]
```

### paver files subcommands

| Subcommand                   | Description                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `list`                       | List files in the workspace. Alias: `ls`.                                                                                |
| `upload PATH [REMOTE_NAME]`  | Upload a local file or folder. `REMOTE_NAME` is a simple name, not a path.                                               |
| `download NAME [LOCAL_PATH]` | Download a file or folder. If you don't specify `LOCAL_PATH`, the file or folder is downloaded to the current directory. |
| `remove NAME`                | Remove a file from the workspace. Alias: `rm`.                                                                           |
| `clear`                      | Remove all remote files. Alias: `removeall`.                                                                             |

### paver files options

| Option                     | Description                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------- |
| `--json`                   | Output the result as JSON. Accepted by `list`.                                         |
| `-y, --yes`, `-f, --force` | Skip the confirmation prompt. `remove` and `clear` prompt for confirmation by default. |

### paver files examples

Upload a file from your local machine to the sandbox workspace.

```text
paver files upload ./terraform/main.tf
```

Download a file from the sandbox workspace to the current directory on your local machine.

```text
paver files download generated-policy.json
```

## paver info

Show the CLI, core library, and server versions, server connection details, and authentication and account details.

```text
paver info [--json]
```

### paver info options

| Option   | Description                |
| -------- | -------------------------- |
| `--json` | Output the result as JSON. |

### paver info examples

Show version, connection, and account details as JSON.

```text
paver info --json
```

## paver keyring

Store and manage secrets that can be injected into the sandbox at runtime. Values are encrypted and are never shown after they are stored. For information about common keys and how injection works, see [Storing your secrets in the keyring](https://paver.ibm.com/docs/core-concepts/keyring.md).

```text
paver keyring [list | add NAME [SOURCE] [--ttl DURATION] | remove NAME | clear] [-y, --yes] [-f, --force]
```

Running `paver keyring` with no subcommand is the same as running `paver keyring list`.

### paver keyring subcommands

| Subcommand          | Description                                                                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list`              | List stored credential keys. Values are not shown. Alias: `ls`.                                                                                                             |
| `add NAME [SOURCE]` | Add a secret. `NAME` can contain only letters, numbers, and underscores (`A-Za-z0-9_`), and can be up to 64 characters. For valid `SOURCE` values, see the following table. |
| `remove NAME`       | Remove a stored credential. Alias: `rm`.                                                                                                                                    |
| `clear`             | Clear all durable secrets from the keyring.                                                                                                                                 |

Secret values can't be passed as arguments. Use one of the following sources.

| `SOURCE` value          | Description                                                                    |
| ----------------------- | ------------------------------------------------------------------------------ |
| `env://VARIABLE`        | Read the secret from an environment variable.                                  |
| `file://RELATIVE_PATH`  | Read the secret from a file by using a path relative to the current directory. |
| `file:///ABSOLUTE_PATH` | Read the secret from a file by using an absolute path.                         |
| Omitted                 | Enter the secret at an interactive prompt.                                     |

### paver keyring options

| Option                     | Description                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `--ttl DURATION`           | How long the secret is kept. Used with `add`. If not specified, the default is `24h`. The maximum is `30d`. |
| `-y, --yes`, `-f, --force` | Skip the confirmation prompt. `clear` prompts for confirmation by default.                                  |

### paver keyring examples

Add a secret from an environment variable and keep it for 7 days.

```text
paver keyring add MY_API_KEY env://MY_API_KEY --ttl 7d
```

Add a secret from a file.

```text
paver keyring add MY_API_KEY file://api-key.txt
```

### Exporting keyring entries in a chat session

To inject a stored secret into the shell environment of the active conversation, use the `/keyring export` slash command inside `paver chat`.

| Slash command                     | Description                                               |
| --------------------------------- | --------------------------------------------------------- |
| `/keyring export NAME`            | Export the entry as `$NAME` (the uppercased key name).    |
| `/keyring export NAME as ENV_VAR` | Export the entry with a custom environment variable name. |
| `/keyring export PREFIX_*`        | Export all entries that match a prefix.                   |

## paver login

Authenticate with IBM Cloud. By default, Paver detects your environment and chooses a login method. Use the options to choose a method yourself, such as an API key for scripts or the device flow for headless and remote machines.

```text
paver login [--apikey API_KEY] [--sso] [--json]
```

### paver login options

| Option             | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `--apikey API_KEY` | Log in by using an IBM Cloud API key.                |
| `--sso`            | Show a menu to select the SSO authentication method. |
| `--json`           | Output the result as JSON.                           |

Some options can't be combined:

- `--sso` can't be used with `--apikey`.

### paver login examples

Log in through your browser and select an account context.

```text
paver login
```

Log in by using an API key that is stored in an environment variable.

```text
paver login --apikey $CLOUD_API_KEY
```

To switch between IBM Cloud accounts after you sign in, use the `/context` command in [IBM Paver chat commands reference](https://paver.ibm.com/docs/tui-reference.md).

## paver logout

Clear your saved authentication credentials. This command has no options.

```text
paver logout
```

## paver memory

View or clear the long-term memories that Paver has stored from past conversations. For information about how memory works, see [Building persistent memory and context in Paver](https://paver.ibm.com/docs/core-concepts/memory.md).

```text
paver memory (list | show MEMORY_ID | add CONTENT | remove MEMORY_ID | clear | export [FILE] | import FILE) [--json] [-y, --yes] [-f, --force]
```

### paver memory subcommands

| Subcommand         | Description                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `list`             | List all stored memories. Alias: `ls`.                                                                      |
| `show MEMORY_ID`   | Show a specific memory.                                                                                     |
| `add CONTENT`      | Add a new memory.                                                                                           |
| `remove MEMORY_ID` | Remove a memory. `MEMORY_ID` can be the memory number from the `list` output or the memory ID. Alias: `rm`. |
| `clear`            | Delete all memories.                                                                                        |
| `export [FILE]`    | Export memories to YAML. If not specified, the default file name is `paver-memories-DATE.yaml`.             |
| `import FILE`      | Import memories from a YAML file. Memories whose content already exists are skipped.                        |

### paver memory options

| Option                     | Description                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------- |
| `--json`                   | Output the result as JSON. Accepted by `list` and `show`.                              |
| `-y, --yes`, `-f, --force` | Skip the confirmation prompt. `remove` and `clear` prompt for confirmation by default. |

### paver memory examples

Add a memory.

```text
paver memory add "I work in the us-east region on the payments project"
```

Export your memories to a YAML file.

```text
paver memory export my-memories.yaml
```

## paver shell

Open an interactive shell in your sandbox container, or register and manage shell host bindings. For information about sandbox contents, reconnection behavior, and custom shell hosts, see [Using the Paver interactive shell](https://paver.ibm.com/docs/core-concepts/shell.md).

```text
paver shell [--continue | -c, --conversation CONVERSATION_ID]
paver shell (current | list | register NAME | use NAME | remove NAME)
```

### paver shell subcommands

If you don't specify a subcommand, `paver shell` opens a shell in the sandbox for the current (or a new) conversation.

| Subcommand      | Description                             |
| --------------- | --------------------------------------- |
| `current`       | Show the currently selected shell host. |
| `list`          | List available shell hosts.             |
| `register NAME` | Register a new shell host binding.      |
| `use NAME`      | Switch to a different shell host.       |
| `remove NAME`   | Remove a shell host.                    |

### paver shell options

| Option                               | Description                                             |
| ------------------------------------ | ------------------------------------------------------- |
| `--continue`                         | Attach to the sandbox of the most recent conversation.  |
| `-c, --conversation CONVERSATION_ID` | Attach to the sandbox of a specific conversation by ID. |

### paver shell examples

Open a shell in the sandbox of your most recent conversation.

```text
paver shell --continue
```

List available shell hosts.

```text
paver shell list
```

## paver skills

Alias: `paver skill`

List and manage your custom skills that let you extend Paver by adding your own expertise for Paver to leverage in your sessions. For more information, see [Extending Paver with skills](https://paver.ibm.com/docs/core-concepts/skills.md).

```text
paver skills (list | upload PATH | remove SKILL_NAME) [--json] [-y, --yes] [-f, --force]
```

### paver skills subcommands

| Subcommand          | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `list`              | List all custom skills. Alias: `ls`.                                                         |
| `upload PATH`       | Upload a custom skill. `PATH` can be a skill directory, a `.zip` file, or a `skill.md` file. |
| `remove SKILL_NAME` | Remove a custom skill. Alias: `rm`.                                                          |

### paver skills options

| Option                     | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `--json`                   | Output the result as JSON. Accepted by `list`.                              |
| `-y, --yes`, `-f, --force` | Skip the confirmation prompt. `remove` prompts for confirmation by default. |

### paver skills examples

Upload a skill from a directory.

```text
paver skills upload ./skills/my-custom-skill
```

Remove a skill without a confirmation prompt.

```text
paver skills remove my-custom-skill -y
```

## paver update

Update the CLI to the latest version. The CLI checks for updates automatically. Run this command to update immediately.

```text
paver update [--check] [--force] [-y, --yes]
```

### paver update options

| Option      | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `--check`   | Check for updates without installing them.                  |
| `--force`   | Reinstall the current version, which is useful for repairs. |
| `-y, --yes` | Automatically confirm the installation.                     |

### paver update examples

Update to the latest version.

```text
paver update
```

Check for updates without installing them.

```text
paver update --check
```

Enable or disable automatic updates by setting a configuration value.

```text
paver config set update.auto_detect true    # Enable auto-update
paver config set update.auto_detect false   # Disable auto-update
```

## paver user

Manage your user account and the personal data that is stored on the Paver server.

```text
paver user delete-data [--dry-run] [--json]
```

### paver user subcommands

| Subcommand    | Description                                              |
| ------------- | -------------------------------------------------------- |
| `delete-data` | Delete all of your personal data from this Paver server. |

### paver user options

| Option      | Description                                              |
| ----------- | -------------------------------------------------------- |
| `--dry-run` | Preview what would be deleted without deleting anything. |
| `--json`    | Output the result as JSON.                               |

### paver user examples

Preview what would be deleted without deleting anything.

```text
paver user delete-data --dry-run
```

## paver whoami

Show the currently authenticated user, IAM ID, environment, server URL, and selected account.

```text
paver whoami [--json]
```

### paver whoami options

| Option   | Description                |
| -------- | -------------------------- |
| `--json` | Output the result as JSON. |

### paver whoami examples

Show the authenticated user and account as JSON.

```text
paver whoami --json
```

## Global options

These options apply to all `paver` commands.

```text
paver COMMAND [--help] [--version] [--theme THEME] [--config KEY=VALUE] [--config-dir PATH] [--no-update-check]
```

| Option               | Description                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| `--help`, `-h`       | Show help for a command.                                                                             |
| `--version`, `-V`    | Show the CLI, core library, and server versions.                                                     |
| `--theme THEME`      | The color theme. Valid values are `auto`, `dark`, and `light`.                                       |
| `--config KEY=VALUE` | Override a configuration value for this invocation only. You can specify this option more than once. |
| `--config-dir PATH`  | Use a custom configuration directory instead of `~/.paver`.                                          |
| `--no-update-check`  | Skip the automatic update check on startup, which is useful for scripts.                             |