PuppyOne CLI

The public npm-distributed command-line entry point for PuppyOne Desktop and PuppyOne Cloud.

The puppyone npm package is public and Apache-2.0 licensed. This source repository is private. It contains CLI code only; it does not contain the Desktop Electron application or the PuppyOne Cloud backend.

First-time installation

1. Check the prerequisite

Install Node.js 22.14 or newer. Node includes npm.

node --version
npm --version

PuppyOne Desktop currently runs on macOS. PuppyOne Cloud commands remain cross-platform.

2. Install the CLI

Install the current public release:

npm install --global puppyone

Do not use sudo. Installing the npm package only installs the puppyone command; it does not download or open Desktop and it has no postinstall script.

3. Verify the installation

puppyone --version
puppyone --help

The current release prints 0.3.1.

4. Start PuppyOne Desktop

puppyone

Bare puppyone is the primary Desktop entry point. The explicit equivalent is:

puppyone desktop

On first launch the CLI checks the official Desktop preview release, downloads the architecture-matching immutable package, verifies its exact size and SHA-256, prepares the application, and opens it. Later launches reuse the verified cached application when the release has not changed.

Cloud login is not required to install or open Desktop.

Run once without a global installation

Use npx when you do not want a persistent global command:

npx --yes puppyone@latest

Arguments follow the package name:

npx --yes puppyone@latest --help
npx --yes puppyone@latest cloud auth login

First Cloud session

The preferred Cloud namespace is explicit:

puppyone cloud auth login
puppyone cloud auth whoami
puppyone cloud org ls
puppyone cloud project ls

Then select or create the required organization, project, and Access Point before using filesystem commands:

puppyone cloud ap login root --api-url https://api.puppyone.com
puppyone cloud fs ls /

Upgrade or remove the CLI

npm install --global puppyone@latest
npm uninstall --global puppyone

Removing the npm package removes the puppyone command. 0.3.1 does not expose a separate desktop uninstall command, so npm removal does not claim to remove the Desktop preview cache, user projects, credentials, or application settings.

See Getting Started for the complete first-run and troubleshooting guide.

Command index

This index describes commands that are available in [email protected].

Root routing

| Command | Behavior | | --- | --- | | puppyone | Resolve and open PuppyOne Desktop; this is the default | | puppyone desktop | Explicit Desktop entry point | | puppyone cloud ... | Preferred namespace for PuppyOne Cloud | | puppyone <cloud-group> ... | Compatible 0.2.x Cloud form | | puppyone --help | Show root help without Desktop side effects | | puppyone --version | Show the CLI version without Desktop side effects |

Desktop options

| Command | Behavior | | --- | --- | | puppyone desktop | Prepare and open Desktop detached from the terminal | | puppyone desktop --foreground | Keep Desktop attached to the terminal | | puppyone desktop --prepare-only | Download and verify without opening | | puppyone desktop --clean | Replace the cached preview before opening | | puppyone desktop --clean --prepare-only | Replace and verify without opening | | puppyone desktop --intro | Replay the full PuppyOne intro animation | | puppyone desktop --no-intro | Skip the intro animation for this launch | | puppyone desktop -- <args...> | Forward arguments to the preview launcher | | puppyone desktop --help | Show Desktop help without downloading or opening |

The full PuppyOne dog animation plays once per CLI version in an interactive terminal. Later launches stay fast; use --intro whenever you want to replay it.

desktop install, desktop open, desktop update, desktop status, and desktop uninstall are not commands in 0.3.1.

Cloud global options

Place Cloud global options before the Cloud command:

puppyone cloud --json fs ls /
puppyone cloud --api-url http://localhost:9090 auth login

| Option | Purpose | | --- | --- | | -u, --api-url <url> | Override the PuppyOne API URL | | -k, --api-key <key> | Override the API key or token | | --json | Return structured output for agents and scripts | | -v, --verbose | Enable verbose output | | -p, --project <id> | Override the active Project | | -o, --org <id> | Override the active Organization |

Cloud command groups

| Group | Subcommands | | --- | --- | | auth | login, logout, whoami, targets, targets switch, targets remove | | org | ls, create, use, current, info, members, invite, rm, update, remove-member, set-role, leave | | project / p | ls, create, use, current, info, update, rm | | template / tmpl | ls / list, show, use | | access | schema, providers, auth, auth-status, add, ls, info, pause, resume, rm, key, refresh, trigger, update, logs, run | | gateway | providers, connect, ls, info, rm, refresh | | chat | Interactive chat or one-shot --message | | config | show, set, path, reset | | ap | login, use, list, current, logout, clear, plus filesystem compatibility commands | | fs | ls, tree, find, grep, cat, head, tail, stat, write, mkdir, touch, upload, download, cp, mv, rmdir, rm, semantics | | status | Show the active Project dashboard |

Use nested help for options and arguments:

puppyone cloud --help
puppyone cloud auth --help
puppyone cloud access add --help
puppyone cloud fs grep --help

The complete current command tree, compatibility rules, examples, and side-effect boundaries are in Command Reference.

0.2.x compatibility

Existing explicit Cloud groups remain valid:

puppyone auth login
puppyone fs ls /
puppyone project ls

When upgrading from 0.2.x, the important routing change is that bare puppyone now opens Desktop. New documentation and automation should prefer the explicit puppyone cloud ... namespace.

Desktop preview behavior

On every Desktop invocation, the CLI checks the uncached release pointer at:

https://downloads.puppyone.ai/desktop/internal/mac/latest/latest.json

It selects the terminal-preview asset for the current Mac architecture, downloads that release's immutable package to a private temporary directory, and verifies the exact byte size and SHA-256 digest from the release pointer. Only the verified local .tgz is passed to npm exec. The mutable latest package alias is never executed.

While Apple Developer ID provisioning is pending, that small terminal-preview launcher downloads the macOS app archive, verifies its exact byte size and SHA-256 digest, caches it for the current user, and opens the app in a separate window. If the release has not changed, the verified cached app is reused.

The CLI does not remove quarantine attributes or disable Gatekeeper. This terminal preview is temporary; the permanent public distribution path is a Developer ID-signed and notarized macOS release.

Installing the npm package does not launch Desktop and does not install a postinstall script. Desktop is downloaded only when the user runs puppyone or puppyone desktop.

At present, the Desktop command is macOS-only; the available CPU architecture depends on the preview artifacts published for that release. Cloud commands remain cross-platform.

Development

npm ci
npm test
node bin/puppyone.js --help

To exercise the Desktop command against a locally built preview package:

PUPPYONE_DESKTOP_ALLOW_FILE_URL=1 \
PUPPYONE_DESKTOP_PACKAGE_URL=file:///absolute/path/to/preview.tgz \
node bin/puppyone.js desktop

To exercise release-pointer resolution against a non-production host:

PUPPYONE_DESKTOP_ALLOW_CUSTOM_HOST=1 \
PUPPYONE_DESKTOP_LATEST_URL=https://example.test/desktop/latest.json \
node bin/puppyone.js desktop

Direct remote-package overrides must also provide PUPPYONE_DESKTOP_PACKAGE_BYTES and PUPPYONE_DESKTOP_PACKAGE_SHA256. Local file: overrides remain available only with PUPPYONE_DESKTOP_ALLOW_FILE_URL=1.

The live Cloud integration suite requires a running PuppyOne backend:

npm run test:integration

Repository boundaries

• src/desktop/ owns only the Desktop command and launcher delegation.
• src/cloud/ and src/commands/ own the Cloud CLI.
• Desktop application builds remain in puppyone-desktop.
• Cloud services remain in puppyone.

License

Apache License 2.0. See LICENSE and NOTICE.

Security

Please use GitHub's private vulnerability reporting flow described in SECURITY.md. Do not publish unpatched vulnerability details in a public issue.

Releases

The npm package is published manually by a maintainer with npm two-factor authentication. GitHub Actions runs checks but never publishes the package. See RELEASING.md.