prdworks

Connect each local Git checkout to one repository in a prd.works organization. Sign in with Google in the web app. Your personal space is available immediately; create or join a team to use a shared space. The web app calls organizations teams and repositories spaces. CLI selectors and existing bindings keep their names.

npm install -g prdworks
cd YOUR_PROJECT
prdworks init --org 'Acme' --repo 'API'
prdworks status
prdworks context

The standalone installer also works without Node.js:

curl -fsSL https://prd.works/install.sh | sh

On Windows, use irm https://prd.works/install.ps1 | iex in PowerShell. Installation never requires access to the private source repository.

Install the PRD Works plugin once for each editor you use:

prdworks plugin install --host codex
prdworks plugin install --host claude
prdworks plugin install --host cursor

Use --host all to install for all three, or --dry-run to preview without changes. Codex and Claude Code use their native plugin commands and must be on PATH. Cursor uses its local plugin directory; reload Cursor and check Customize. Your administrator must allow local imports. Start a new agent session after installation. The same plugin works across all your organizations.

Run prdworks init for browser selection of an organization, then its repository. Use prdworks init --org 'Acme' to restrict the choices to one organization, or add --repo 'API' for an explicit pair. Repository names alone are rejected. There is no global active organization: each checkout retains its own stable pair. In noninteractive agent sessions use --no-browser --instructions none, then approve the displayed URL and comparison code in your browser.

Plugin assets ship inside the npm package and standalone binary. Re-run plugin install after upgrading the CLI. Locally modified or unmanaged plugin directories are not overwritten. plugin export --host codex --output ./prdworks-codex exports a portable marketplace (use claude or cursor for those formats). Public marketplace listings are a separate release step. See the plugin guide.

init resolves explicit selectors, then an existing binding, then registered Git remotes. SSH and HTTPS forms on GitHub, GitLab.com, and Bitbucket Cloud can find the same repository. Fork owners remain distinct. Ambiguity requires a choice; unmatched remotes require explicit selection or registration. A cached login alone never selects a repository. Browser approval can discover all repositories available to the signed-in person. Cached tokens only list their own authorized repositories. Unbound setup without a complete organization/repository pair goes directly to browser approval, even if a cached token matches the Git remote. A partial cache therefore cannot hide another organization's matching repository.

Init creates .prdworks/prdworks.toml, which contains the API origin and stable organization and repository IDs, alongside .prdworks/binding.json with a local checkout ID. It adds /.prdworks/ to .gitignore. Keep the entire directory local, including the TOML. Each clone runs prdworks init to connect and authorize access. Both bindings are credential-free and contain no absolute paths. Moving the checkout preserves its identity. Fresh clones and worktrees get their own local marker while connecting to the same web repository. Conflicting TOML/local bindings are rejected instead of silently retargeted. Legacy public-key configs are upgraded without changing their repository or removing comments. An existing root-level prd-works.toml moves to .prdworks/prdworks.toml during init.

Every teammate approves their own computer. Repository-scoped tokens stay in the user's config directory, outside Git, and current organization membership is checked on every request. Removing a member also stops their old CLI tokens. For CI, supply PRDWORKS_TOKEN and explicit selectors (or an existing binding), then run prdworks init --instructions none. Use --no-browser to approve from another device. login --dev works only against an explicitly enabled development API and is never the production onboarding flow.

Init can add startup instructions to AGENTS.md or CLAUDE.md while preserving existing instructions. They tell agents to run prdworks context before work, read current document versions, and inspect freely named folders. The plugin provides the shared skill; direct CLI use also works without it. No MCP installation is required. repositories lists accessible repositories; spaces and link remain compatibility aliases.

Documents and folders

Folder commands require CLI 0.6.0 or later and a server with the document-space migration applied. Upgrade with npm install -g prdworks@latest or rerun the standalone installer, then reinstall the editor plugin to update its instructions.

The web app works without Git or a CLI. This optional interface connects a checkout to an existing space using the stable repository IDs in the binding.

prdworks folders list
prdworks folders create "Notes"
prdworks folders create "Phase 3" --parent FOLDER_ID
prdworks docs create "Meeting notes" --file notes.md --folder FOLDER_ID
prdworks docs read DOCUMENT_ID
prdworks docs update DOCUMENT_ID --file notes.md --expected-version VERSION
prdworks docs move DOCUMENT_ID --folder FOLDER_ID --expected-version VERSION
prdworks folders move FOLDER_ID --parent PARENT_ID
prdworks folders rename FOLDER_ID "Ideas"

Omit --folder or --parent when moving to place an item at the root. Folder archive and restore retain descendant archive flags. Document titles and folder names never assign a workflow. The old --kind creation flag is deprecated and has no effect. work, progress, and document status commands are retired; existing work is preserved in ordinary Markdown after the server migration.

Replace VERSION with the version returned by the latest docs read before each write. Updates and moves increment the version. On conflict, read the document again and reconcile your change before retrying.

Use docs archive or docs restore with --expected-version VERSION for a document. Use folders archive FOLDER_ID or folders restore FOLDER_ID for a folder. docs list and folders list include archived entries and their archive flags. Use context for currently visible documents, or inspect ancestor folder flags when working with the complete tree.

context returns document metadata with folder paths and unresolved discussions marked for agents. It returns at most 200 documents and 20 discussions, with truncation flags. Fetch current content with docs read; context is not a full Markdown export. discuss list and discuss send keep discussions on their documents. Sending requires an explicit user request. --relay-agents marks a message for agents to fetch and does not send a notification to a running agent.