---
name: projects-cli
description: Use this skill to operate, troubleshoot, and automate the Projects app CLI, including browser auth, workspace selection, project records, contacts, knowledge, links, files, past-performance profiles, proposal responses, source intake, and SAM.gov search.
---

# Projects CLI

Use this skill for requests that operate the `mere-projects`/`projects`/`pastperf` CLI or the API routes behind it.

## Scope

- CLI command surface in `projects/cli/*`, especially:
  - `cli/projects.ts`
  - `cli/auth.ts`
  - `cli/session.ts`
  - `cli/run.ts`
- CLI auth routes under `src/routes/api/cli/v1/auth/*`.
- Workspace-scoped JSON/file APIs under `src/routes/api/projects`, `src/routes/api/past-performance`, `src/routes/api/proposals`, and `src/routes/api/sources`.
- Internal product command bridge at `src/routes/api/internal/zerosmb/workspaces/[workspaceId]/commands/[command]/+server.ts`.

## Base Commands

1. Build the CLI:
   - `cd /Users/nerd/mere/projects && pnpm build:cli`
2. Authenticate:
   - `./dist/run.js auth login`
   - Local app smoke test: `./dist/run.js auth login --base-url http://127.0.0.1:5173`
   - `./dist/run.js auth whoami`
3. Select a workspace:
   - `./dist/run.js workspace list`
   - `./dist/run.js workspace use <id|slug|host>`
4. Prefer `--json` for automation and `--workspace <id|slug|host>` for one-off workspace overrides.

When `auth login` does not pass `--workspace`, the shared CLI auth layer selects a deterministic default by role (`owner`, then `admin`, then member) and workspace name. Human login output includes the selected workspace and count of available workspaces.

## Environment

| Variable | Purpose |
| --- | --- |
| `PROJECTS_BASE_URL` | Base URL for `auth login`; defaults to `https://projects.meresmb.com` |
| `PASTPERF_BASE_URL` | Legacy alias for `PROJECTS_BASE_URL` |
| `XDG_STATE_HOME` | Overrides session storage root |

Session file:

- `~/.local/state/mere-projects/session.json`

## Command Families

- `auth login|whoami|logout`
- `workspace list|current|use`
- `completion [bash|zsh|fish]`
- `project list|get|create|update|archive|delete`
- `contact list|upsert|delete --project <projectId>`
- `knowledge list|upsert|delete --project <projectId>`
- `link list|upsert|delete --project <projectId>`
- `file list|upload|download|delete --project <projectId>`
- `profile list|get|create|update|delete`
- `proposal list|get|create|update|delete|draft|generate-draft|analysis|analyze`
- `source list|get|upsert|patch|capture`
- `sam search`

Mutations accept `--data '<json>'` or `--data-file payload.json`. Common project/profile/proposal fields also have first-class flags.
Permanent deletes require `--yes --confirm <exact-id>`; soft project archive does not require the exact-confirm guard.

## References

- [command-reference.md](references/command-reference.md): command matrix and examples.
- [route-map.md](references/route-map.md): CLI command to route mapping.
- `/Users/nerd/mere/projects/README.md`: app overview and local development.

## Safe Edit Boundaries

For CLI behavior:

- `cli/projects.ts`
- `cli/auth.ts`
- `cli/session.ts`
- `cli/run.ts`

For auth/session routing:

- `src/routes/api/cli/v1/auth/*`
- `src/lib/server/cli-auth.server.ts`
- `src/lib/server/workspace-session.server.ts`

For project command bridge behavior:

- `src/lib/server/project-commands.server.ts`
- `src/routes/api/internal/zerosmb/workspaces/[workspaceId]/commands/[command]/+server.ts`