Metadata-Version: 2.4
Name: projectmemory-cli
Version: 0.1.3
Summary: Project Memory CLI — developer context in your terminal
License: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic>=2
Requires-Dist: questionary>=2
Requires-Dist: rich>=13
Requires-Dist: tomli-w>=1
Requires-Dist: typer[all]>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Project Memory CLI

Developer context in your terminal — a Python CLI client for [projectmemory.app](https://projectmemory.app).

## Installation

```bash
pip install projectmemory-cli
```

Or from source:

```bash
git clone https://github.com/your-org/projectmemory-cli
cd projectmemory-cli
pip install -e ".[dev]"
```

Both `pm` and `projectmemory` are registered as executable names.

## Quick Start

```bash
# Authenticate (opens browser)
pm login

# Create a project and start its first session
pm project create

# Or resume an existing project/session
pm resume "My App"

# See your current context
pm memory show

# Work with tasks
pm task list
pm task add "Implement login"
pm task done 42      # completes task, then optionally links a commit
pm done              # interactive task completion shortcut

# Capture notes
pm capture "Don't forget to update the Stripe webhook URL"

# Report an issue
pm issue add "Login fails on mobile Safari"

# End your session with the shared backend review
pm session end
```

## Commands

### Authentication
| Command | Description |
|---|---|
| `pm login` | Authenticate via browser |
| `pm logout` | Revoke token |
| `pm whoami` | Show current user |
| `pm auth status` | Check auth status |
| `pm doctor` | Diagnose CLI config, auth, backend, project, session, and Git state |

### Projects
| Command | Description |
|---|---|
| `pm project list` | List all projects |
| `pm project create` | Create a project (interactive) |
| `pm project current` | Show current project + session |
| `pm project link` | Link this directory to a project |
| `pm project unlink` | Remove directory mapping |
| `pm web` | Open project in browser |

### Work Sessions
| Command | Description |
|---|---|
| `pm resume [project]` | Start or resume a session |
| `pm session status` | Show all active sessions |
| `pm session end` | End the current session |

### Project Memory
| Command | Description |
|---|---|
| `pm memory show` | Display all memory fields |
| `pm memory status set [text]` | Update Current Status |
| `pm memory context set [text]` | Update Important Context |
| `pm memory update` | Interactive memory update, including open issues |

### Next Action
| Command | Description |
|---|---|
| `pm next` | Show current Next Action |
| `pm next set [text]` | Set Next Action (interactive menu) |
| `pm next task <id>` | Link a task as Next Action |
| `pm next issue <id>` | Link an issue as Next Action |
| `pm next clear` | Clear Next Action |

### Tasks
| Command | Description |
|---|---|
| `pm task list` | List tasks; supports `--open`, `--completed`, `--snoozed`, `--all` |
| `pm task add [title]` | Create a task |
| `pm task done <id>` | Complete task + optional commit link |
| `pm done` | Interactive task completion shortcut |
| `pm task snooze <id>` | Snooze task |
| `pm task reopen <id>` | Reopen task |
| `pm task edit <id>` | Edit task |
| `pm task delete <id>` | Delete task |

### Notes
| Command | Description |
|---|---|
| `pm note list` | List notes |
| `pm note add [content]` | Create a note; supports `--title`, `--editor`, `--stdin` |
| `pm note search <query>` | Search notes |
| `pm capture [text]` | Quick note shortcut |
| `pm note edit <id>` | Edit a note |
| `pm note delete <id>` | Delete a note |

### Issues
| Command | Description |
|---|---|
| `pm issue list` | List issues; supports `--open`, `--resolved`, `--all` |
| `pm issue add [description]` | Report an issue |
| `pm issue resolve <id>` | Mark issue as resolved |
| `pm issue reopen <id>` | Reopen issue |
| `pm issue edit <id>` | Edit issue |
| `pm issue delete <id>` | Delete issue |

### Commits
| Command | Description |
|---|---|
| `pm commit link` | Interactive recovery flow for linking a commit to a completed task |
| `pm commit link HEAD --task 24` | Directly link a commit/ref to a completed task |

## Configuration

Configuration is stored at `~/.config/projectmemory/config.toml`.

The default `api_url` is the Project Memory site root, for example `https://projectmemory.app`. The CLI adds API paths such as `/api/cli/...` internally.

```bash
pm config show         # show all settings
pm config set api_url https://your-instance.example.com
pm config reset        # restore defaults
```

### Environment variables

| Variable | Description |
|---|---|
| `PROJECTMEMORY_API_URL` | API base URL |
| `PROJECTMEMORY_TOKEN` | Token override (skip keyring) |
| `PROJECTMEMORY_PROJECT` | Current project ID override |
| `PROJECTMEMORY_NO_COLOR` | Disable color output |


## Diagnostics

Run a read-only diagnostic report when troubleshooting local configuration or support issues:

```bash
pm doctor
pm doctor --json
pm doctor --verbose
pm doctor --no-network
```

`pm doctor` never prints authentication tokens, refresh tokens, passwords, private keys, or OAuth secrets. It exits with `0` when healthy, `1` when warnings are present, and `2` when critical issues prevent normal CLI use.

## Directory Linking

Link the current git repository to a project so `pm` knows which project to use automatically:

```bash
cd ~/code/my-app
pm project link "My App"

# Now pm commands in this directory use "My App" automatically
pm task list    # no --project needed
```

## How Sessions Work

The CLI shares the session model with the web app. Sessions must be active for write operations (creating tasks, notes, issues, updating memory).

- `pm resume` starts or resumes the backend session for the selected project
- `pm resume` can offer an optional Smart Resume when meaningful work changed while you were away; generation always requires confirmation and uses 1 AI Assist
- `pm session end` shows the shared factual Session Review and finalizes that exact session
- After finalization, the deterministic Project Memory Review may offer an optional Smart Handoff draft; generation and every regeneration require confirmation and use 1 AI Assist
- Smart Resume is informational. Smart Handoff remains a draft until you explicitly publish selected fields through the shared Project Memory service
- If the web app ends your session, the CLI will show a clear error and ask you to `pm resume` again
- A user can have active sessions in multiple projects, but the CLI has one current project
- Switching projects can end the current project session, keep it active, or cancel

The Web app and CLI use the same backend sessions, review snapshots, Project Memory operations, permissions, and AI Assist accounting. Presentation differs, but saved outcomes stay synchronized.

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=projectmemory_cli --cov-report=term-missing

# Lint
ruff check projectmemory_cli/

# Type check
mypy projectmemory_cli/
```

## Security

- Tokens are stored in the OS keyring (or `~/.config/projectmemory/credentials.json` with `chmod 600` as fallback)
- Passwords are never stored
- The `PROJECTMEMORY_TOKEN` environment variable overrides stored credentials (read-only)
- Tokens can be revoked remotely via `pm logout` or from the web app at projectmemory.app/settings
# project_memory_cli
