PaperClipAI/docs/cli/setup-commands.md at db4defdfbfc704d93678071db2e9afa86cdde3fa

0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-06 21:05:21 +02:00

Files

T

Nicky LeachandPaperclip fdb9a4880d fix(security): route paperclipai CLI guidance through safe npx form (CWE-78) (#11400 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip provides CLI commands and guidance for operators and
agents
> - The `pnpm paperclipai` script can pass argument values through a
shell
> - Shell re-parsing can execute command substitutions inside quoted
values
> - This pull request routes guidance through inert-argv `npx
paperclipai` commands and adds regression coverage
> - The benefit is safer operator guidance across documentation and
runtime hints

## Linked Issues or Issue Description

This pull request fixes a command-injection-class defect in Paperclip
CLI guidance.

**What happened?**

The `pnpm paperclipai <sub> --flag "$VALUE"` form can re-parse argument
values through a shell. A command substitution inside a quoted value can
execute on the host.

**Expected behavior**

Paperclip guidance must pass CLI values as inert argument values.
Host-derived values must not appear in copyable commands.

**Steps to reproduce**

1. Run a Paperclip guidance command that uses the `pnpm paperclipai`
script.
2. Provide a quoted value that contains a command substitution.
3. Observe that the shell can evaluate the substitution before the CLI
starts.
4. Compare the result with the `npx paperclipai` form.

**Paperclip version or commit**

`5670984b75d109950c968542a0111ebb6967f4da`

**Deployment mode**

All deployment modes that show or use the affected CLI guidance.

**Installation method**

Built from source and installed CLI guidance.

**Agent adapter(s) involved**

Not adapter-specific (core bug).

**Database mode**

Not database-related.

**Access context**

Both.

**Additional context**

The earlier merged PR
[#11343](https://github.com/paperclipai/paperclip/pull/11343) used the
unsafe `pnpm exec paperclipai` form. This fresh PR replaces that
guidance with the safe `npx paperclipai` form.

## What Changed

- Standardize documentation and runtime hints on `npx paperclipai`.
- Remove the broken `pnpm exec paperclipai` guidance.
- Use a static `<host>` placeholder in private-hostname guidance.
- Add regression tests for unsafe forms, continued lines, static hosts,
and offline guidance.

## Verification

- `git diff --check
origin/master...origin/fix/paperclipai-cli-npx-safe-invocation` passes.
- The branch adds `server/src/__tests__/cli-invocation-safety.test.ts`
and updates private-hostname tests.
- CI must run the new tests, typecheck, lint, and build checks.
- Local Vitest execution was not available because this worktree has no
installed Vitest binary.

## Risks

- The change affects operator and agent documentation text.
- The runtime hints now show `<host>` instead of a request-derived host
value.
- No database schema or migration changes exist.
- CI will detect any missed unsafe invocation or type error.

## Model Used

OpenAI GPT-5, exact model ID `gpt-5`, with tool use and code-review
assistance. The model used repository inspection, Git operations, and PR
preparation.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] CI ran the test suites and they pass; local test execution was
unavailable in this worktree
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I addressed all Greptile and reviewer comments before requesting
merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-08-14 22:11:16 -07:00

3.0 KiB

Raw Blame History

title, summary

title	summary
Setup Commands	Onboard, run, doctor, and configure

Instance setup and diagnostics commands.

`paperclipai run`

One-command bootstrap and start:

pnpm paperclipai run

Does:

Auto-onboards if config is missing
Runs paperclipai doctor with repair enabled
Starts the server when checks pass

Choose a specific instance:

npx paperclipai run --instance dev

`paperclipai onboard`

Interactive first-time setup:

pnpm paperclipai onboard

If Paperclip is already configured, rerunning onboard keeps the existing config in place. Use paperclipai configure to change settings on an existing install.

First prompt:

Quickstart (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
Advanced setup: full interactive configuration

Start immediately after onboarding:

pnpm paperclipai onboard --run

Non-interactive defaults + immediate start (opens browser on server listen):

pnpm paperclipai onboard --yes

On an existing install, --yes now preserves the current config and just starts Paperclip with that setup.

`paperclipai doctor`

Health checks with optional auto-repair:

pnpm paperclipai doctor
pnpm paperclipai doctor --repair

Validates:

Server configuration
Database connectivity
Secrets adapter configuration, including AWS Secrets Manager non-secret env config when selected
Storage configuration
Missing key files

`paperclipai configure`

Update configuration sections:

pnpm paperclipai configure --section server
pnpm paperclipai configure --section secrets
pnpm paperclipai configure --section storage

--section secrets updates the deployment-level provider used as the fallback for secrets that do not target a specific company vault. Per-company provider vaults (named instances, default vault selection, multiple vaults per provider, coming-soon GCP/Vault) live in the board UI under Company Settings → Secrets → Provider vaults and the /api/companies/{companyId}/secret-provider-configs API.

`paperclipai env`

Show resolved environment configuration:

pnpm paperclipai env

This now includes bind-oriented deployment settings such as PAPERCLIP_BIND and PAPERCLIP_BIND_HOST when configured.

`paperclipai allowed-hostname`

Allow a private hostname for authenticated/private mode:

npx paperclipai allowed-hostname my-tailscale-host

Local Storage Paths

Data	Default Path
Config	`~/.paperclip/instances/default/config.json`
Database	`~/.paperclip/instances/default/db`
Logs	`~/.paperclip/instances/default/logs`
Storage	`~/.paperclip/instances/default/data/storage`
Secrets key	`~/.paperclip/instances/default/secrets/master.key`

Override with:

PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run

Or pass --data-dir directly on any command:

npx paperclipai run --data-dir ./tmp/paperclip-dev
npx paperclipai doctor --data-dir ./tmp/paperclip-dev

3.0 KiB Raw Blame History

paperclipai run

paperclipai onboard

paperclipai doctor

paperclipai configure

paperclipai env

paperclipai allowed-hostname