ProjectCtx documentation

CLI reference

Reference for ProjectCtx commands, flags, credentials, and diagnostics.

The projectctx command configures supported clients, runs diagnostics, scans repositories, and provides scoped authentication for reviewed Code Memory operations.

Installation

npm install -g @projectctx/agent@alpha
projectctx --help

Add --debug to commands when collecting sanitized diagnostic output.

Core Commands

Command	Purpose
`projectctx connect --dry-run`	Preview supported-client configuration
`projectctx connect`	Apply supported-client configuration
`projectctx doctor`	Inspect runtime, configuration, and optional CLI authentication
`projectctx scan [rootPath]`	Produce a read-only repository overview
`projectctx mcp`	Run the local stdio MCP server for a configured client

Connect

projectctx connect [--dry-run] [--debug]

Always run --dry-run first. The applied command preserves unrelated configuration and backs up changed files.

Doctor

projectctx doctor [--debug]

Doctor prints structured checks without credential values. It cannot inspect OAuth credentials owned by an external AI client.

Scan

projectctx scan [rootPath] [options]

Option	Meaning
`--max-repos <n>`	Maximum repositories to include
`--max-files <n>`	Maximum selected files per repository
`--max-excerpt <n>`	Maximum excerpt bytes
`--max-depth <n>`	Maximum directory traversal depth
`--overview-depth <n>`	Directory overview depth
`--ignore <name>`	Repeatable ignored name
`--task-term <term>`	Repeatable task-relevance term
`--debug`	Print sanitized debug diagnostics

Local MCP Server

projectctx mcp [--debug]

An MCP client launches this stdio process. Do not run a second persistent copy manually.

Scoped CLI Authentication

Hosted AI clients use OAuth. The commands below are for separately issued, workspace-scoped agent credentials used by CLI Code Memory operations.

projectctx login --token "<token>" [--api-url <url>] [--allow-file-token-fallback] [--debug]
projectctx logout [--debug]
projectctx whoami [--debug]
projectctx workspaces [--debug]
projectctx workspace use <workspaceId> [--debug]

login validates the credential before saving it. The CLI prefers the operating system credential store. File storage requires explicit --allow-file-token-fallback consent and uses mode 0600.

You can supply PROJECTCTX_TOKEN for temporary automation. Avoid command-line arguments where shell history could retain a credential.

Workspace-Owner Token Commands

These commands require appropriate workspace-owner authorization:

projectctx token create --scopes <a,b> [--name <name>] [--expires-in-days <n>] [--workspace <id>] [--no-store] [--debug]
projectctx token list [--workspace <id>] [--debug]
projectctx token revoke <credentialId> [--workspace <id>] [--debug]

--auth-token <token> and --api-url <url> are available for explicit administrative automation. Never include token values in documentation, issue trackers, shell transcripts, or shared debug output.

Environment Variables

Variable	Purpose
`PROJECTCTX_TOKEN`	Temporary scoped CLI credential
`PROJECTCTX_API_URL`	API base URL override
`PROJECTCTX_WORKSPACE_ID`	Explicit workspace selection

Production normally uses https://projectctx.com; remove stale overrides when diagnosing connection failures.

Exit And Error Behavior

Commands return a non-zero exit code on failure. Structured failures use:

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "where": "command",
    "message": "Safe diagnostic message"
  }
}

See Troubleshooting for common error codes and recovery steps.