Metadata-Version: 2.4
Name: labtab
Version: 0.2.0
Summary: Command-line interface for LabTab (Wetware Ltd). Manage your lab from the terminal.
Author-email: Wetware Ltd <support@wetware.ai>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic[email]>=2.5
Requires-Dist: rich>=13.7.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: tomli-w>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# labtab

Command-line interface for [LabTab](https://labtab.app) - the lab management
platform for Principal Investigators. Manage grants, papers, literature,
posters, talks, results, meetings, tasks, projects, and people from your
terminal.

Built by [Wetware Ltd](https://wetware.co.uk).

## Install

```bash
pip install labtab
```

Requires Python 3.10+.

## Shell completion

`labtab` ships tab completion for bash, zsh, fish, and PowerShell:

```bash
# Install completion for your current shell (then restart the shell)
labtab --install-completion

# Or print the completion script to wire up manually
labtab --show-completion
```

## Quickstart

```bash
# Pair your terminal with your LabTab account (opens a browser window)
labtab auth login

# Pair with a read-only key instead - mutating commands will be rejected
labtab auth login --read-only

# See which labs you belong to
labtab labs list
labtab labs members list
labtab labs members invite new.member@example.com --role PhD
labtab labs members set-role 42 "PhD"
labtab labs members archive 42
labtab labs members transfer-pi 42
labtab labs settings show
labtab labs settings update --timezone Europe/London

# Review or update your account profile
labtab account show
labtab account update --first-name Alex --last-name Harston

# Manage API keys for scripts and integrations
labtab api-keys list
labtab api-keys create "CI deploy" --scope read:papers --scope write:notes
labtab api-keys revoke 42

# Open a command-line overview of your lab (--limit rows per section)
labtab home
labtab home --limit 10

# Create a meeting - --datetime takes ISO-8601 or a relative form
labtab meetings create --title "Standup" --datetime "tomorrow 10:00" --lab smith-neuro-lab
labtab meetings create --title "1:1" --datetime "next monday 09:00" --lab smith-neuro-lab

# Search across your accessible workspace
labtab search "atlas figures"

# Review and clear unread notifications
labtab notifications list
labtab notifications mark-all-read

# Review PI-only lab activity
labtab audit-logs list
labtab audit-logs show 42

# Create and revoke external share links
labtab shares list --type paper --object-id 12
labtab shares create paper 12 collaborator@example.com --permission comment
labtab shares revoke 7

# Review upcoming lab deadlines
labtab deadlines list

# Track recommendation letters and drafts
labtab letters list
labtab letters show 12
labtab letters drafts 12
labtab letters save-draft 12 --file draft.html
labtab letters status 12 Submitted

# Browse lab wiki pages
labtab wiki list
labtab wiki tree

# Browse and export collaborative notes
labtab notes list meeting 42
labtab notes create meeting 42 --text "Decision captured"
labtab notes update 123 --file follow-up-notes.txt
labtab notes export meeting 42 --format md --output meeting-notes.md

# List your grants
labtab grants list

# Inspect a single grant
labtab grants show gr_abc123

# Show the next 7 days of meetings
labtab meetings upcoming --days 7

# Get JSON for scripting
labtab papers list --json | jq '.[] | .title'

# Curate relevant literature and journal-club collections
labtab literature list --reading-status to_read
labtab literature create --title "Spatial transcriptomics benchmark" \
  --author "Maya Singh" --journal "Nature Methods" --year 2026 \
  --reading-status to_read
labtab literature collection-add 3 12
labtab literature comment 12 --body "Discuss in journal club"

# Track a conference poster
labtab posters create --title "Spatial transcriptomics atlas" \
  --conference ISSCR --presented-date 2026-06-12 --author-id 42 \
  --file poster.pdf

# Prepare and archive lab talks
labtab talks list --upcoming
labtab talks create --title "Organoid atlas update" --type Seminar \
  --date 2026-07-01 --speaker-id 42 --project-id 3
labtab talks archive 11

# Capture research outputs and link them to papers, posters, talks, or grants
labtab results create --title "Figure 2 quantification" \
  --description "Validated cell counts" --author 42 --project 3 \
  --file counts.csv --kind data
labtab results link 8 --target-type paper --target-id 22 --relationship supports

# Export your whole lab as a zip
labtab export --format zip --lab smith-neuro-lab
```

## Commands

Commands that fetch structured data support `--json` for machine-readable
output. Most lab-scoped commands accept `--lab <slug>` to override the default
lab from your config; PI-only audit logs accept the lab ID used by the API
permission check.

| Command                        | What it does                              |
| ------------------------------ | ----------------------------------------- |
| `labtab home`                  | Account and lab command-center overview; `--limit` rows per section (1-50, default 5) |
| `labtab search <query>`        | Search across accessible LabTab records   |
| `labtab audit-logs list`       | PI-only lab audit log, filter by action or actor |
| `labtab audit-logs show <id>`  | Show one audit row with metadata          |
| `labtab shares list`           | Review active or revoked external share links |
| `labtab shares create <type> <id> <email>` | Create and email a secure share link |
| `labtab shares revoke <id>`    | Revoke a share link in the active lab     |
| `labtab notifications list`    | Review account notifications              |
| `labtab notifications mark-read <id>` | Mark one notification read         |
| `labtab notifications mark-all-read` | Mark all notifications read         |
| `labtab deadlines list`        | Review grants, tasks, papers, and other deadlines |
| `labtab letters list`          | Review recommendation letter requests |
| `labtab letters show <id>`     | Show one letter request              |
| `labtab letters drafts <id>`   | List saved draft versions            |
| `labtab letters save-draft <id>` | Save a new draft from `--text` or `--file` |
| `labtab letters status <id> <status>` | Update request status          |
| `labtab wiki list`             | Browse lab wiki pages                    |
| `labtab wiki show <id>`        | Show a wiki page                         |
| `labtab wiki tree`             | Show the wiki hierarchy                  |
| `labtab notes list <type> <id>` | Browse collaborative notes for an entity |
| `labtab notes show <id>`       | Show one saved note snapshot             |
| `labtab notes create <type> <id>` | Create a note from `--text` or `--file` |
| `labtab notes update <id>`     | Replace note content from `--text` or `--file` |
| `labtab notes export <type> <id>` | Export entity notes as Markdown or text |
| `labtab auth login`            | Pair this terminal with your account; `--read-only` requests a key that cannot modify data |
| `labtab auth logout`           | Forget the local API key                  |
| `labtab auth whoami`           | Show the signed-in user and default lab   |
| `labtab auth set-base-url`     | Update the stored API base URL            |
| `labtab account show`          | Show your server-side account profile and lab roles |
| `labtab account update`        | Update editable profile fields            |
| `labtab api-keys list`         | List API keys owned by the signed-in user |
| `labtab api-keys create <name>` | Create an API key and print the one-time secret |
| `labtab api-keys revoke <id>`  | Revoke one of your API keys               |
| `labtab api-keys active-count` | Show active API key usage                 |
| `labtab labs list`             | Labs you have membership in               |
| `labtab labs members list`     | List active lab memberships               |
| `labtab labs members show <user>` | Show one lab membership                |
| `labtab labs members invite <email>` | Invite one member through the admin-gated invite API |
| `labtab labs members set-role <user> <role>` | Change a member role through the PI-gated API |
| `labtab labs members archive <user>` | Archive a lab membership             |
| `labtab labs members restore <user>` | Restore an archived lab membership   |
| `labtab labs members transfer-pi <user>` | Transfer the PI role through the dedicated API |
| `labtab labs settings show`    | Show readable lab settings                |
| `labtab labs settings update`  | Update admin-only lab settings            |
| `labtab grants list`           | Grants, filter by `--status`              |
| `labtab grants show <id>`      | Grant detail card                         |
| `labtab papers list`           | Papers, filter by `--year`                |
| `labtab papers show <id>`      | Paper detail with authors, DOI            |
| `labtab literature list`       | Relevant literature, filter by search, collection, status, or classification |
| `labtab literature show <id>`  | Literature detail with authors, DOI, relevance, and collections |
| `labtab literature create`     | Create a literature/reference record      |
| `labtab literature collections` | List literature collections              |
| `labtab literature collection-create` | Create a literature collection     |
| `labtab literature collection-add <collection> <literature>` | Add literature to a collection |
| `labtab literature collection-remove <collection> <literature>` | Remove literature from a collection |
| `labtab literature comments <id>` | List comments on a literature record   |
| `labtab literature comment <id>` | Add a literature comment                |
| `labtab literature claim <id>` | Claim literature as a lab paper           |
| `labtab literature mark-external <id>` | Mark literature as external work |
| `labtab posters list`          | Posters, searchable by title, venue, or author |
| `labtab posters show <id>`     | Poster detail with related project, papers, grants |
| `labtab posters create`        | Create a poster, optionally uploading a PDF |
| `labtab talks list`            | Talks, filter by status, type, speaker, project, or grant |
| `labtab talks show <id>`       | Talk detail with speakers, projects, papers, and links |
| `labtab talks create`          | Create a talk record                          |
| `labtab talks archive <id>`    | Archive a talk without deleting notes         |
| `labtab results list`          | Research results, filter by search, project, or task |
| `labtab results show <id>`     | Result detail with attached evidence          |
| `labtab results create`        | Create a result, optionally uploading evidence files |
| `labtab results links <id>`    | List research objects linked to a result      |
| `labtab results link <id>`     | Link a result to a paper, poster, talk, or grant |
| `labtab meetings upcoming`     | Meetings in the next `--days` (default 7) |
| `labtab meetings show <id>`    | Meeting detail card                       |
| `labtab meetings create`       | Create a meeting; `--datetime` takes ISO-8601 or `today 14:30` / `tomorrow 10:00` / `monday 09:00` / `next monday 09:00` |
| `labtab tasks list`            | Tasks, filter by `--status`               |
| `labtab tasks show <id>`       | Task detail card                          |
| `labtab projects list`         | Projects                                  |
| `labtab projects show <id>`    | Project detail card                       |
| `labtab people list`           | Lab members                               |
| `labtab people show <id>`      | Person detail card                        |
| `labtab export`                | Download a full lab export                |

## Configuration

`labtab` reads and writes its config at `~/.config/labtab/config.toml`.
Override the path with the `LABTAB_CONFIG_FILE` environment variable.

```toml
[api]
base_url = "https://labtab.app/api/v1"

[auth]
api_key = "lab_api_xxxxxxxx"
user_email = "pi@example.com"
default_lab_id = 42
default_lab_slug = "smith-neuro-lab"
```

The config file is written with `0600` permissions so other users on the
machine cannot read your API key.

If you later move the product domain, you can rewrite just the hostname while
preserving the rest of the API path:

```bash
labtab auth set-base-url --host labtab.io
```

## Pydantic models

The package ships two sets of models:

* `labtab.models` (re-exports `labtab.models.api`) - hand-curated, **lenient**
  models the CLI uses internally. They tolerate extra or renamed backend
  fields so a CLI install doesn't break when the server ships new columns.
* `labtab.models.generated` - a **strict**, auto-generated snapshot of the
  backend's OpenAPI schema. Useful if you want to script against the API
  directly with precise types.

### Regenerating the strict snapshot

```bash
# with a running backend at localhost:8000
datamodel-codegen \
  --url http://localhost:8000/api/v1/schema/ \
  --output src/labtab/models/generated.py \
  --output-model-type pydantic_v2.BaseModel \
  --input-file-type openapi

# or from a snapshotted schema
cd backend && python manage.py spectacular --file /tmp/schema.yml
datamodel-codegen --input /tmp/schema.yml \
  --output src/labtab/models/generated.py \
  --output-model-type pydantic_v2.BaseModel \
  --input-file-type openapi
```

## License

MIT. See `LICENSE`.
