phresh

phresh [-v | --version] command [subcommand] [options]

phresh is the command-line interface for PhreshOS, a local system that runs programs built with web technology and serves a Desktop in the browser. The owner uses those Programs from the Desktop. This command reaches the same System at the same time, with the owner's authority.The binary comes from the npm package @phreshos/cli (`phresh` maps to `dist/cli.js`). It owns command parsing, terminal output, release download, and native service management. Runtime calls go through @phreshos/node. The CLI does not invent a second System protocol: phresh execute sends one JSON Execute request and prints the JSON result.With no arguments, phresh prints help. phresh command --help describes one command. phresh describe prints the machine-readable contract without contacting the System. phresh skill prints a short briefing meant for an agent before its first command.Project commands work on a Program directory: create, init, pack, install, uninstall, dev, and start. system installs and manages the local System service, and also queries a System that is already running. The other groups (program, process, endpoint, service, window, connection, session, operation, fetch) require a running System.Human-readable output is the default for runtime commands. --json writes the whole result as one JSON value.

-v, --version

Print the CLI version.

On runtime commands, write the result as one JSON value on stdout.

Create a Program project from the starter bundled with the CLI. Optional --name name, --package-manager `bun`|`npm`|`pnpm`|`yarn`, and --no-install (write files without installing dependencies). Omitted values are prompted in a terminal.

Write phresh.config.ts for the project in the current directory, reading identity, version, and description from package.json. Declare endpoints with --server and --client, plus location, command, and dev-command options. --force replaces an existing config file.

Run the project's optional build command, then package the production files declared for each endpoint.

With no name, build and install the Program in the current project. A name installs that official Program's verified release. --run launches one default Process afterward. --purge deletes existing storage for that Program. Requires a running System.

Remove an installed Program. With no name, uses the Program declared by this project. --purge also removes Processes, data, and runtime state. Requires a running System.

Run the development Program attached to this terminal. Ending the command stops the Program. The Client URL must respond within 15 seconds. Program options are only --run-option-name=value.

Same attached lifecycle as dev, using the production declarations. An optional build command runs first. The Program's exit status becomes this command's status.

Download the official stable System release, register the user service, start it, and print the Desktop address. --purge deletes PHRESHOS_HOME before the new System starts. The first install also provisions the welcome Program sprout.

Stop and remove the System service and installation. --purge also deletes PHRESHOS_HOME. Without it, persistent data is kept.

Show version, Desktop address, service state, and whether automatic startup is enabled.

Print the installed System version.

Start or stop the background service, or turn automatic startup on or off.

Name, version, and release of the running System. --json is available.

Ask the System to open a resource, for example an image file URI.

Run a read-only SQL statement against System logs. --values is a JSON array of bound parameters.

Print a summary of the running System: version, Desktop address, Program and Process counts, connections, and appearance. --json prints the same data as one JSON value.

Discover Programs. list (optional --installed-only, --search, --limit, --offset), inspect --program identity, agent --program identity (agent documentation), definition, startup commands (get-startup, set-startup, remove-startup), pin commands (pinned, pin, unpin), permission commands (get-permission, list-permissions, allows-permission, allow-permission, deny-permission), logs, and wait.

Live Program executions. list, inspect, create, find-or-create (also findOrCreate), exit, and wait. --process is the Process identity or Program-local name. --program selects the owning Program when a name is used.

One Process endpoint. inspect, start, stop, wait-ready, wait-lifecycle, ask, publish, and wait. --endpoint is `server` or `client`. endpoint memory reads and changes a running Client's memory (get, set, delete, entries).

Named endpoint services. list, inspect, wait-ready, ask, publish, wait, wait-lifecycle, and wait-discovery. ask requires --program, --process, --endpoint server, and --event. Optional --payload is JSON.

The Client window of one Process. inspect, move, resize, set-geometry, minimize, maximize, set-title, set-header, raise, and wait. Positions and sizes accept pixels or workspace-relative expressions such as `50%`.

Send one Execute request encoded as JSON. Discover operations with operation list and operation describe.

Print the CLI contract. --all includes every command under the path. --json emits the contract as data. Does not contact the System.

Print what PhreshOS is and which commands to run first. Does not contact the System.

PHRESHOS_HOME

Absolute directory for the System's persistent state. The default is ~/.phreshos. The service log is service.log in that directory. The Desktop URL is the contents of the desktop file there when it matches `http://localhost:` plus a port. Otherwise the CLI reports `http://localhost:4300`.

Port request passed to the service the next time it starts.

On Linux the installation root is $XDG_DATA_HOME/phreshos/system, or ~/.local/share/phreshos/system when the variable is unset. A set value must be an absolute path.

Program project file written by phresh init. --force replaces an existing file.

The npm package declares Node.js >= 20.10. The System repository's install instructions ask for Node.js 24.15 or newer before phresh system install.Commands that talk to a running System fail until phresh system install has completed and the service is up. phresh is not a reduced agent account: it acts as the owner.dev and start stay in the foreground. Stopping the command stops the Program. dev and start reject ordinary flags other than --run-option-name=value.system install downloads a release and changes the user service. --purge on system install or system uninstall deletes PHRESHOS_HOME.

npm(1), node(1), bun(1), systemctl(1)

Source code · Homepage · Documentation