Skip to main content
Shell Commands allow Agents to run standard UNIX and custom shell commands. Shell commands are a way to run automations using internal tools and scripts, or can be used when a native Unpage plugin doesn’t yet exist for a system you’re running. Shell commands can give your agents access to anything available on your $PATH.
  • shell_[command]: Each configured shell command becomes a tool with the shell_ prefix
Unlike other agentic tools, Unpage will only run the shell commands you have explicitly configured.

​
Configuration

Enable the Shell Commands plugin by editing the ~/.unpage/profiles/<profile_name>/config.yaml file:

​
Defining Shell Commands

You must explicitly define each shell command you want to make available to Agents. For example:
Each command requires a handle (which must be unique), a description (which helps the LLM decide when to use it) and the command itself.

​
Commands With Arguments

Shell commands can accept arguments, which are escaped and then passed to the command. All arguments you define are then required. If you have a script that has accepts optional arguments, configure it multiple times with and without the arguments (make sure to give each version its own handle and description).
You must list each argument under args, where the format is <arg_name>: <description of the argument>. The descriptions are important in order to guide the LLM to pass in the arguments correctly. Then within the command itself, include the argument in curly brackets like: command: ls -lah {<arg_name>}.

​
Environment

Shell commands are run within the same environment as Unpage itself. That means they have access to the same configuration, environment variables, etc. as the main process.

​
Tools

Each shell command you define ends up as an Agent / MCP tool, named with the shell_ prefix. For example, a command with the handle get_current_directory will result in a new tool named shell_get_current_directory.

​
Developing & Testing Commands

The easiest way to develop and test new shell commands is by using the unpage mcp tools subcommands, which will invoke tools directly from the command line. To list all tools, including your custom shell commands, run:
To call a tool via the CLI and test your command, you can run:
For example:
Or commands with arguments:
Running your tools directly and making sure they work beforehand will make debugging your Agents much simpler.