Metadata-Version: 2.4
Name: projectmemory-cli
Version: 0.1.0
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 session end` shows the shared backend Session Review and finalizes that exact session
- 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

## 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
