Prompt Shell

psh turns a natural-language shell task into one shell command, shows it for review, and asks before running it.

psh run clean up docker
psh clean up docker
printf %s "clean up docker" | psh run

Install

Install with curl:

curl -fsSL https://raw.githubusercontent.com/modoterra/promptshell/main/bin/psh.sh | sh -s -- install

The -s flag tells sh to read the downloaded script from stdin and pass install to psh.

Or with wget:

wget -qO- https://raw.githubusercontent.com/modoterra/promptshell/main/bin/psh.sh | sh -s -- install

By default, the installer writes psh to $HOME/.local/bin. Override the destination with PSH_INSTALL_DIR:

curl -fsSL https://raw.githubusercontent.com/modoterra/promptshell/main/bin/psh.sh | PSH_INSTALL_DIR=/usr/local/bin sh -s -- install

Uninstall the installed psh binary:

psh uninstall

Requirements

• jq is required.
• curl is required for hosted providers.
• dd and stty are required for interactive approval.
• codex is required only when using PSH_PROVIDER=codex.

Setup

Run the interactive setup flow before your first hosted-provider request:

psh setup

psh setup requires an interactive terminal. It asks for:

• Provider: OpenAI, Fireworks, or Codex when codex is installed.
• Model: choose a listed model or enter a custom model.
• API key: required for OpenAI and Fireworks; not used for Codex.

The setup command saves config to ${XDG_CONFIG_HOME:-$HOME/.config}/psh/config.json with file mode 600.

Change only the configured model later without re-entering the provider or API key:

psh setup model

psh setup model requires an existing config from psh setup.

You can also configure providers with environment variables:

OPENAI_API_KEY=... psh run list large files
PSH_PROVIDER=fireworks FIREWORKS_API_KEY=... psh run list large files
PSH_PROVIDER=codex psh run list large files
PSH_PROVIDER=codex CODEX_MODEL=gpt-5.4 psh run list large files

Provider/model environment variables:

• PSH_PROVIDER: openai, fireworks, or codex.
• OPENAI_API_KEY, OPENAI_MODEL for OpenAI.
• FIREWORKS_API_KEY, FIREWORKS_MODEL for Fireworks.
• CODEX_MODEL for Codex. The model is passed to codex exec with -m.
• PSH_API_KEY, PSH_MODEL as provider-agnostic fallbacks.

Environment variables override saved config for that run.

Usage

Use explicit run:

psh run show ports listening on this machine

Or omit run; unknown commands are treated as a prompt:

psh show ports listening on this machine

Pipe a prompt through stdin:

printf %s "show ports listening on this machine" | psh run

More examples:

# Inspect the system
psh run show disk usage by top-level directory
psh run find files larger than 500 MB under the current directory

# Work with Git
psh run show commits on this branch that are not on main
psh run undo the last commit but keep the changes staged

# Compose with other shell commands
printf %s "list docker containers using the most memory" | psh run
printf %s "archive all log files older than 30 days" | psh run

# Use implicit run mode
psh compress all png files in this directory
psh replace spaces with underscores in filenames here

In an interactive terminal, psh previews the generated command and asks for approval. Press y to run it. Press Enter, Esc, n, or anything else to cancel.

Without a controlling terminal, psh prints only the generated command to stdout and does not execute it. This keeps the CLI scriptable:

command=$(printf %s "show ports listening on this machine" | psh run)
printf '%s\n' "$command"

Safety

Model output is treated as a proposal, not an instruction. Interactive runs show an AI review notice before approval, and higher-risk model results include risk and explanation metadata.

psh always requires interactive approval before execution. Non-interactive runs never execute generated commands.

Development

Install test dependencies:

npm install

Run syntax checks and the Bats integration suite:

make test

Run the local installer smoke check:

make install-smoke

Contributing

• Read CONTRIBUTING.md before opening a pull request.
• Use GitHub Issues for bugs and feature requests.
• Report security vulnerabilities privately; see SECURITY.md.

Community

Use common sense and decency. There is no formal code of conduct. We reserve the right to moderate this community to the extent of the law and the policy of the host. Write community@modoterra.xyz if you need us.

License

Prompt Shell is released under the MIT License. See LICENSE.