Pocket Trash CLI

Install the CLI:

npm install -g @pocket-trash/cli

Initialize local paths from the root of your local pocket-trash checkout:

cd ../pocket-trash
pocket-trash init

Commands

| Command | Description | | --- | --- | | pocket-trash init | Initialize repository and worktree paths from a Pocket Trash checkout. | | pocket-trash linear | Show the authenticated Pocket Trash Linear workspace and user. | | pocket-trash linear archive | Preview or archive old completed, canceled, and duplicate Linear issues. | | pocket-trash linear orphans | List URLs of non-archived issues without a project. | | pocket-trash linear report | Show project and active-ticket summaries using Clack formatting. | | pocket-trash settings | Show saved repository and worktree paths. | | pocket-trash settings update <repo> <worktree> | Update a repository's worktree directory. | | pocket-trash sync | Fast-forward clean Pocket Trash repositories. | | pocket-trash upgrade | Show the npm upgrade command. | | pocket-trash version | Show the installed CLI version. | | pocket-trash worktree [branch] | Create a worktree, prompting for omitted choices. | | pocket-trash worktree check | List local branches without worktrees. | | pocket-trash worktree del [worktree] | Delete one worktree or select worktrees interactively. |

Every command has a help screen:

pocket-trash --help
pocket-trash worktree --help
pocket-trash worktree del --help
pocket-trash help worktree del

Create worktrees

Pass a branch as <initials>/<name>. Pocket Trash is the default repository; use --repo for the CLI, skills, or localizations repository. Each new worktree installs its frozen dependencies, then invokes its locked skills executable to install the Pocket Trash skills for Codex and Claude Code. Worktree creation never downloads an unreviewed executable dynamically.

pocket-trash worktree ra/my-change
pocket-trash worktree -r cli ra/my-change

Pocket Trash worktrees can configure personal database selection interactively or entirely through flags:

pocket-trash worktree ra/my-change -pd -i ra
pocket-trash worktree ra/my-change --no-personal-database

Run pocket-trash worktree --help for every option and example.

Linear workspace

Show the current Pocket Trash workspace and user:

pocket-trash linear

Render project and active-ticket summaries as terminal-native Clack tables:

pocket-trash linear report

Active tickets include every non-archived issue, regardless of status or project. The report starts with total active tickets and tickets without a project, then breaks down projects, ticket statuses, priorities, and assignees. Backlog work, Feature Requests (Tracker), and Bug (Tracker) have dedicated project tables; they are tracked by stable IDs, so renaming them does not break the report.

List every non-archived issue without a project, one URL per line:

pocket-trash linear orphans

Preview completed, canceled, and duplicate issues older than 14 days by default. --older-than accepts days or hours; add -y to archive the matches.

pocket-trash linear archive --older-than 4h
pocket-trash linear archive --older-than 4h -y

These commands require the linear CLI authenticated to the pocket-trash workspace. Any user with access to that workspace can run them.

Delete worktrees

del removes the worktree and its local branch. Use -r to select a repository and -y to accept deletion without confirmation. The old delete command remains supported.

pocket-trash worktree del -r skills worktrees/skills/my-change
pocket-trash worktree del -y worktrees/my-change

Development

Use pnpm from this directory:

pnpm install
pnpm test
pnpm lint
pnpm typecheck
pnpm build
pnpm security:audit

Format files:

pnpm format

Use conventional commits. Commit messages and PR titles are checked with commitlint.

Changesets

Add a changeset for user-facing changes:

pnpm changeset

Changesets update package.json and CHANGELOG.md during release.

Release

Merges to main automatically release pending Changesets through Publish. To retry a failed release from remote main, use an authenticated GitHub CLI:

pnpm release

This command queues the workflow; it does not publish the local checkout or wait for completion. Check the returned run link, or use gh run list --workflow publish.yml and gh run watch <run-id> --exit-status. Humans and agents use the same npm Trusted Publishing workflow without local npm login or an npm access token.

The workflow audits, builds, tests, lints, typechecks, and packs the versioned package before pushing its release commit and annotated tag atomically. It publishes the validated tarball through npm OIDC, then creates a GitHub release using that version's changelog entry. Provenance is explicitly disabled because npm does not support it for this private source repository. A retry recovers an incomplete release from its exact tagged source before consuming newer Changesets. Recovery allows up to six minutes for missing npm metadata to propagate before attempting publication. A genuinely unpublished tagged version incurs that wait; longer propagation can still result in a safely rejected duplicate attempt. Completed releases are a no-op; registry and GitHub API errors stop the run. Release commits use [skip ci] to prevent another automatic run.

One-time repository setup:

1. Configure npm's trusted publisher for @pocket-trash/cli: organization Pocket-Trash, repository cli, workflow publish.yml, with direct npm publish permission. Validate it with a successful publish within npm's two-day setup window. After validation, disallow traditional publishing tokens in the npm package's publishing-access settings.
2. Install the release GitHub App on this repository with Contents write access and add it as an always-allowed bypass actor on the main ruleset. Keep approval and Security requirements for ordinary PRs.
3. Set repository variable RELEASE_APP_ID and Actions secret RELEASE_APP_PRIVATE_KEY. The workflow creates a short-lived App credential for git writes and uses GitHub's job token for release metadata. npm uses OIDC only; do not configure NPM_TOKEN or NODE_AUTH_TOKEN.

The workflow accepts only main, uses GitHub-hosted runners, serializes releases, and installs npm 11.20.0 for OIDC. Recovery checks out the recorded tag and installs its frozen lockfile before rebuilding, then restores current main and its dependencies before processing newer Changesets. npm configuration is isolated in the runner's temporary directory. Missing setup fails safely; retry after configuring it. Setup is tracked by ENG-428.

Dependency security

External npm releases are quarantined for seven days. Exact internal Pocket Trash packages are exempt so coordinated releases remain possible. A required Security check and daily audit block high/critical vulnerabilities before build or release.

Until an upstream fix is published for GHSA-vfj7-8cjw-p6xm, [email protected] has a local pnpm patch that rejects brace and parenthesis nesting above 100 levels before recursive processing. Every audit first tests the installed Changesets dependency to verify the mitigation. Only this advisory is excluded from the version-based audit; other high/critical advisories and registry failures still block builds and releases. Replace the patch with an upstream fixed release and remove the exclusion together when available.

For an urgent reviewed release, add only its exact package and version to minimumReleaseAgeExclude in pnpm-workspace.yaml. Include a comment linking the Linear issue and its UTC maturity/removal time, then remove the exception after it matures. Never lower the global age or add a scope wildcard.