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.

View as markdown

On this page

For commands used inside the interactive chat session, see IBM Paver chat commands reference.

Prerequisites#

Complete the following steps to install the Paver CLI:

Install the Paver CLI by running the following command on MacOS or Linux:
```
curl -fsSL https://paver.cloud.ibm.com/cli/install | bash
```
Log in with your IBM Cloud® account credentials by running paver login. For more information, see paver login. If you don't have an IBM Cloud account, you can create an account.

For more information about installing the CLI or instructions for Windows, see Installing the IBM Paver CLI. To keep the CLI up to date, see 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.

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.

paver ask examples#

List all VPCs in the eu-de region.

paver ask "list all VPCs in eu-de"

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

paver ask "run terraform plan" --continue

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

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. For information about how safe mode and edit mode work, see Safety mode.

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.
`--no-color`	Disable colored output.

paver chat examples#

Start a new session.

paver chat

Resume the most recent conversation.

paver chat --continue

Resume a specific conversation by ID.

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.

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.

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.

paver config list

Disable automatic update checks by setting a configuration value.

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.

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.

paver conversation list --json

Export a conversation as a Markdown file.

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

Delete a conversation without a confirmation prompt.

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.

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.

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.

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.

paver files upload ./terraform/main.tf

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

paver files download generated-policy.json

paver info#

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

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.

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.

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.

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

Add a secret from a file.

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.

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.

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

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

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.

paver logout#

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

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.

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.

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

Export your memories to a YAML file.

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.

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.

paver shell --continue

List available shell hosts.

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.

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.

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

Remove a skill without a confirmation prompt.

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.

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.

paver update

Check for updates without installing them.

paver update --check

Enable or disable automatic updates by setting a configuration value.

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.

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.

paver user delete-data --dry-run

paver whoami#

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

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.

paver whoami --json

Global options#

These options apply to all paver commands.

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.