mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-26 10:26:26 +01:00
fix: fail closed on unusable Codex auth during sandbox auth merge
When reusing a Codex sandbox, the workspace-restore step now performs an auth-merge check before adopting the sandbox's auth.json. The merge fails closed when: - host or sandbox Codex auth is unusable (missing token or account) - the subscription payload shapes differ between host and sandbox - subscription account identities do not match Additional hardening: node absence on PATH during the embedded decision script now exits non-zero instead of silently falling through. Co-change comments link parseAuth (the embedded script) to hasUsableAuthPayload (codex-home.ts) so a future auth-format change cannot silently diverge between the two implementations. Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Harold KimandPaperclip committed
commit
98df214917
3422 files changed
+1614966
No files matched your search
@@ -0,0 +1,152 @@
|
||||
---
|
||||
title: Control-Plane Commands
|
||||
summary: Issue, agent, approval, and dashboard commands
|
||||
---
|
||||
|
||||
Client-side commands for managing issues, agents, approvals, and more.
|
||||
|
||||
## Issue Commands
|
||||
|
||||
```sh
|
||||
# List issues
|
||||
pnpm paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
|
||||
|
||||
# Get issue details
|
||||
pnpm paperclipai issue get <issue-id-or-identifier>
|
||||
|
||||
# Create issue
|
||||
pnpm paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
|
||||
|
||||
# Update issue
|
||||
pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
|
||||
|
||||
# Add comment
|
||||
pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]
|
||||
|
||||
# Checkout task
|
||||
pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>
|
||||
|
||||
# Release task
|
||||
pnpm paperclipai issue release <issue-id>
|
||||
```
|
||||
|
||||
## Company Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclipai company list
|
||||
pnpm paperclipai company get <company-id>
|
||||
pnpm paperclipai company current [--company-id <company-id>]
|
||||
|
||||
# Export to portable folder package (writes manifest + markdown files)
|
||||
pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents
|
||||
|
||||
# Preview import (no writes)
|
||||
pnpm paperclipai company import \
|
||||
<owner>/<repo>/<path> \
|
||||
--target existing \
|
||||
--company-id <company-id> \
|
||||
--ref main \
|
||||
--collision rename \
|
||||
--dry-run
|
||||
|
||||
# Apply import
|
||||
pnpm paperclipai company import \
|
||||
./exports/acme \
|
||||
--target new \
|
||||
--new-company-name "Acme Imported" \
|
||||
--include company,agents
|
||||
```
|
||||
|
||||
With agent authentication, use `company list` or `company current` to resolve
|
||||
the scoped company. `company list` first tries the board-wide list; if that is
|
||||
forbidden, it falls back to `--company-id`, `PAPERCLIP_COMPANY_ID`, context, or
|
||||
`/api/agents/me` and returns only that scoped company. `company create` requires
|
||||
board/instance-admin authentication because it is an instance-wide setup
|
||||
command.
|
||||
|
||||
## Agent Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclipai agent list
|
||||
pnpm paperclipai agent get <agent-id>
|
||||
```
|
||||
|
||||
## Skills Commands
|
||||
|
||||
```sh
|
||||
# Browse app-shipped catalog skills without changing company state
|
||||
pnpm paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
|
||||
pnpm paperclipai skills search "pull request" [--json]
|
||||
|
||||
# Inspect catalog metadata and file inventory before install
|
||||
pnpm paperclipai skills inspect github-pr-workflow
|
||||
|
||||
# Install a catalog skill into the company skill library
|
||||
# This does not attach the skill to any agent.
|
||||
pnpm paperclipai skills install github-pr-workflow --company-id <company-id>
|
||||
pnpm paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
|
||||
|
||||
# External sources still use import instead of catalog install
|
||||
pnpm paperclipai skills import ./skills/my-skill --company-id <company-id>
|
||||
pnpm paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
|
||||
|
||||
# Attach desired company skills to an agent after install/import
|
||||
pnpm paperclipai skills agent sync <agent-id> --skill github-pr-workflow --company-id <company-id>
|
||||
```
|
||||
|
||||
## Approval Commands
|
||||
|
||||
```sh
|
||||
# List approvals
|
||||
pnpm paperclipai approval list [--status pending]
|
||||
|
||||
# Get approval
|
||||
pnpm paperclipai approval get <approval-id>
|
||||
|
||||
# Create approval
|
||||
pnpm paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
|
||||
|
||||
# Approve
|
||||
pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
|
||||
|
||||
# Reject
|
||||
pnpm paperclipai approval reject <approval-id> [--decision-note "..."]
|
||||
|
||||
# Request revision
|
||||
pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]
|
||||
|
||||
# Resubmit
|
||||
pnpm paperclipai approval resubmit <approval-id> [--payload '{"..."}']
|
||||
|
||||
# Comment
|
||||
pnpm paperclipai approval comment <approval-id> --body "..."
|
||||
```
|
||||
|
||||
## Activity Commands
|
||||
|
||||
```sh
|
||||
pnpm paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
|
||||
```
|
||||
|
||||
## Dashboard
|
||||
|
||||
```sh
|
||||
pnpm paperclipai dashboard get
|
||||
```
|
||||
|
||||
## Instance Settings
|
||||
|
||||
```sh
|
||||
pnpm paperclipai instance settings:general
|
||||
pnpm paperclipai instance settings:general:update --payload-json '{...}'
|
||||
pnpm paperclipai instance settings:experimental
|
||||
pnpm paperclipai instance settings:experimental:update --payload-json '{...}'
|
||||
```
|
||||
|
||||
Experimental features are opt-in and are provided without compatibility guarantees. They may break, change, or be removed at any time. Use them at your own risk.
|
||||
|
||||
## Heartbeat
|
||||
|
||||
```sh
|
||||
pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
title: CLI Overview
|
||||
summary: CLI installation and setup
|
||||
---
|
||||
|
||||
The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
pnpm paperclipai --help
|
||||
```
|
||||
|
||||
## Global Options
|
||||
|
||||
All commands support:
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--data-dir <path>` | Local Paperclip data root (isolates from `~/.paperclip`) |
|
||||
| `--api-base <url>` | API base URL |
|
||||
| `--api-key <token>` | API authentication token |
|
||||
| `--context <path>` | Context file path |
|
||||
| `--profile <name>` | Context profile name |
|
||||
| `--json` | Output as JSON |
|
||||
|
||||
Company-scoped commands also accept `--company-id <id>`.
|
||||
|
||||
For clean local instances, pass `--data-dir` on the command you run:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
|
||||
```
|
||||
|
||||
## Context Profiles
|
||||
|
||||
Store defaults to avoid repeating flags:
|
||||
|
||||
```sh
|
||||
# Set defaults
|
||||
pnpm paperclipai context set --api-base http://localhost:3100 --company-id <id>
|
||||
|
||||
# View current context
|
||||
pnpm paperclipai context show
|
||||
|
||||
# List profiles
|
||||
pnpm paperclipai context list
|
||||
|
||||
# Switch profile
|
||||
pnpm paperclipai context use default
|
||||
```
|
||||
|
||||
To avoid storing secrets in context, use an env var:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
|
||||
export PAPERCLIP_API_KEY=...
|
||||
```
|
||||
|
||||
Secret operations are available under `paperclipai secrets`:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai secrets declarations --company-id <company-id> --kind secret
|
||||
pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
|
||||
pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
|
||||
pnpm paperclipai secrets doctor --company-id <company-id>
|
||||
pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
|
||||
```
|
||||
|
||||
Context is stored at `~/.paperclip/context.json`.
|
||||
|
||||
## Command Categories
|
||||
|
||||
The CLI has two categories:
|
||||
|
||||
1. **[Setup commands](/cli/setup-commands)** — instance bootstrap, diagnostics, configuration
|
||||
2. **[Control-plane commands](/cli/control-plane-commands)** — issues, agents, approvals, activity
|
||||
@@ -0,0 +1,131 @@
|
||||
---
|
||||
title: Setup Commands
|
||||
summary: Onboard, run, doctor, and configure
|
||||
---
|
||||
|
||||
Instance setup and diagnostics commands.
|
||||
|
||||
## `paperclipai run`
|
||||
|
||||
One-command bootstrap and start:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run
|
||||
```
|
||||
|
||||
Does:
|
||||
|
||||
1. Auto-onboards if config is missing
|
||||
2. Runs `paperclipai doctor` with repair enabled
|
||||
3. Starts the server when checks pass
|
||||
|
||||
Choose a specific instance:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run --instance dev
|
||||
```
|
||||
|
||||
## `paperclipai onboard`
|
||||
|
||||
Interactive first-time setup:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
1. `Quickstart` (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
|
||||
2. `Advanced setup`: full interactive configuration
|
||||
|
||||
Start immediately after onboarding:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai onboard --run
|
||||
```
|
||||
|
||||
Non-interactive defaults + immediate start (opens browser on server listen):
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
pnpm 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:
|
||||
|
||||
```sh
|
||||
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
|
||||
```
|
||||
|
||||
Or pass `--data-dir` directly on any command:
|
||||
|
||||
```sh
|
||||
pnpm paperclipai run --data-dir ./tmp/paperclip-dev
|
||||
pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev
|
||||
```
|
||||
Reference in new issue
Block a user