proteworks 0.1.10__tar.gz → 0.1.11__tar.gz

{proteworks-0.1.10 → proteworks-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proteworks
-Version: 0.1.10
+Version: 0.1.11
 Summary: Sync files with Proteworks using file-browser paths.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -52,6 +52,8 @@ proteworks mcp setup-claude-science
 proteworks mcp doctor
 ```
 
+To switch accounts: `proteworks login --force` (clears the local token and the browser Auth0 session, then opens the sign-in UI). `proteworks logout` only forgets the local token.
+
 After any upgrade: run step 2 again (same `install-system` command), then `doctor`. Do not `uv tool install` again unless `/usr/local/bin/proteworks` is missing.
 
 ### Claude Science connector
@@ -99,20 +101,37 @@ proteworks push ./1UBQ.pdb '~/My Files/test/'
 proteworks push '*.pdb' '~/My Files/pdbs/'
 proteworks push designs.zip '~/My Files/dest/'   # auto-extracts
 proteworks mkdir '~/My Files/campaigns/round6/'
+proteworks recycle '~/My Files/campaigns/old-run/'   # soft delete → recycle bin
 ```
 
-MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push).
+MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push), and `move_to_recycle_bin` for soft-deleting a file, folder/, or wildcard (dry_run by default; set `confirm=true` to execute).
 
 Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs.
 
 Example prompts: list `~/My Files/`, dry-run pull a folder, pull it, push results back.
 
-Optional coaching skills (not required for the server):
+### Agent skills (MCP)
+
+Playbooks ship with the server. Agents should:
+
+1. `list_skills` — catalog (name, description, files)
+2. `get_skill(name)` — `SKILL.md` instructions (default)
+3. `get_skill(name, path="…")` — helpers such as `kernel.py`
+
+Bundled today (canonical under `src/proteworks/skills/`; `skills/` holds symlinks for host import):
 
-- [`skills/proteworks-files/SKILL.md`](skills/proteworks-files/SKILL.md)
-- [`skills/proteworks-workflows/SKILL.md`](skills/proteworks-workflows/SKILL.md)
+- [`protein-studio-molx`](src/proteworks/skills/protein-studio-molx/) — build Protein Studio `.molx` sessions (`SKILL.md` + `kernel.py`)
+- [`proteworks-workflows`](src/proteworks/skills/proteworks-workflows/) — shared prepare/submit/monitor hub
+- [`proteworks-workflow-rfd4-proteina`](src/proteworks/skills/proteworks-workflow-rfd4-proteina/) — RFD4 modes including binder rescue
+- [`proteworks-workflow-rf-diffusion3`](src/proteworks/skills/proteworks-workflow-rf-diffusion3/)
+- [`proteworks-workflow-proteinmpnn`](src/proteworks/skills/proteworks-workflow-proteinmpnn/)
+- [`proteworks-workflow-refolding`](src/proteworks/skills/proteworks-workflow-refolding/)
+- [`proteworks-workflow-structure-prediction`](src/proteworks/skills/proteworks-workflow-structure-prediction/)
+- [`proteworks-workflow-msa-generation`](src/proteworks/skills/proteworks-workflow-msa-generation/)
+- [`proteworks-studio`](src/proteworks/skills/proteworks-studio/) — `.studio` inspect / save-selected
+- [`proteworks-files`](src/proteworks/skills/proteworks-files/) — list/pull/push/recycle
 
-Import via Settings → Skills → Import from GitHub (or upload the folder). Hosts without a Skills UI still get conventions from MCP tool descriptions and this README.
+Add another skill by creating `src/proteworks/skills/<name>/SKILL.md` (plus optional helpers), then symlink `skills/<name>/SKILL.md` → the packaged file for GitHub Skills import. No new MCP tool names are required for playbook-only adds.
 
 ### Tools
 
@@ -120,16 +139,18 @@ Import via Settings → Skills → Import from GitHub (or upload the folder). Ho
 | --- | --- |
 | `auth_status` | Login state, API URL, active org (never the token) |
 | `organization_list` / `organization_set` | Choose organization (`organization_set` needs `confirm=true`) |
+| `list_skills` / `get_skill` | Bundled playbooks (e.g. `.molx`); no login required |
 | `list_files` | Browse a remote path; returns `file_id` + `relative_path` |
 | `pull` / `push` | Transfer with `dry_run` (default true); real transfers need `confirm_transfer=true` |
-| `list_workflows` | Allowlisted agent workflows (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, `msa-generation`) |
+| `list_workflows` | Allowlisted agent workflows (`rf-diffusion3`, `rfd4-proteina`, `proteinmpnn`, `refolding`, `structure-prediction`, `msa-generation`) |
 | `get_workflow_schema` | Full schema with UI-matching defaults |
 | `prepare_workflow_submission` | Merge defaults + overrides; **no submit** (draft body) |
 | `submit_workflow` | Same merge, then submit |
-| `inspect_studio` | Inspect supported `.studio` (proteinmpnn / refolding / rf-diffusion3 / structure_prediction); normalized rows + scores |
+| `inspect_studio` | Inspect supported `.studio` (proteinmpnn / refolding / rf-diffusion3 / rfd4-proteina / structure_prediction); normalized rows + scores |
 | `save_selected_studio` | Same as Studio Save selected → subset `.studio` uploaded + retention finalized (not yet for structure_prediction) |
 | `inspect_proteinmpnn_studio` | Legacy ProteinMPNN flat-row inspect (prefer `inspect_studio`) |
 | `prepare_refolding_from_proteinmpnn_studio` | Build refolding payload + SA handoff from MPNN studio selection (**no submit**) |
+| `list_executions` | List/filter past runs (`workflow_name`, `status`, `output_folder`); includes `design_count` totals |
 | `get_execution` / `list_execution_results` / `cancel_execution` | Status / results / cancel (`cancel_execution` needs `confirm=true`) |
 | `estimate_workflow_cost` | Cost estimate from merged params (same validation as prepare) |
 

{proteworks-0.1.10 → proteworks-0.1.11}/README.md

@@ -38,6 +38,8 @@ proteworks mcp setup-claude-science
 proteworks mcp doctor
 ```
 
+To switch accounts: `proteworks login --force` (clears the local token and the browser Auth0 session, then opens the sign-in UI). `proteworks logout` only forgets the local token.
+
 After any upgrade: run step 2 again (same `install-system` command), then `doctor`. Do not `uv tool install` again unless `/usr/local/bin/proteworks` is missing.
 
 ### Claude Science connector
@@ -85,20 +87,37 @@ proteworks push ./1UBQ.pdb '~/My Files/test/'
 proteworks push '*.pdb' '~/My Files/pdbs/'
 proteworks push designs.zip '~/My Files/dest/'   # auto-extracts
 proteworks mkdir '~/My Files/campaigns/round6/'
+proteworks recycle '~/My Files/campaigns/old-run/'   # soft delete → recycle bin
 ```
 
-MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push).
+MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push), and `move_to_recycle_bin` for soft-deleting a file, folder/, or wildcard (dry_run by default; set `confirm=true` to execute).
 
 Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs.
 
 Example prompts: list `~/My Files/`, dry-run pull a folder, pull it, push results back.
 
-Optional coaching skills (not required for the server):
+### Agent skills (MCP)
+
+Playbooks ship with the server. Agents should:
+
+1. `list_skills` — catalog (name, description, files)
+2. `get_skill(name)` — `SKILL.md` instructions (default)
+3. `get_skill(name, path="…")` — helpers such as `kernel.py`
+
+Bundled today (canonical under `src/proteworks/skills/`; `skills/` holds symlinks for host import):
 
-- [`skills/proteworks-files/SKILL.md`](skills/proteworks-files/SKILL.md)
-- [`skills/proteworks-workflows/SKILL.md`](skills/proteworks-workflows/SKILL.md)
+- [`protein-studio-molx`](src/proteworks/skills/protein-studio-molx/) — build Protein Studio `.molx` sessions (`SKILL.md` + `kernel.py`)
+- [`proteworks-workflows`](src/proteworks/skills/proteworks-workflows/) — shared prepare/submit/monitor hub
+- [`proteworks-workflow-rfd4-proteina`](src/proteworks/skills/proteworks-workflow-rfd4-proteina/) — RFD4 modes including binder rescue
+- [`proteworks-workflow-rf-diffusion3`](src/proteworks/skills/proteworks-workflow-rf-diffusion3/)
+- [`proteworks-workflow-proteinmpnn`](src/proteworks/skills/proteworks-workflow-proteinmpnn/)
+- [`proteworks-workflow-refolding`](src/proteworks/skills/proteworks-workflow-refolding/)
+- [`proteworks-workflow-structure-prediction`](src/proteworks/skills/proteworks-workflow-structure-prediction/)
+- [`proteworks-workflow-msa-generation`](src/proteworks/skills/proteworks-workflow-msa-generation/)
+- [`proteworks-studio`](src/proteworks/skills/proteworks-studio/) — `.studio` inspect / save-selected
+- [`proteworks-files`](src/proteworks/skills/proteworks-files/) — list/pull/push/recycle
 
-Import via Settings → Skills → Import from GitHub (or upload the folder). Hosts without a Skills UI still get conventions from MCP tool descriptions and this README.
+Add another skill by creating `src/proteworks/skills/<name>/SKILL.md` (plus optional helpers), then symlink `skills/<name>/SKILL.md` → the packaged file for GitHub Skills import. No new MCP tool names are required for playbook-only adds.
 
 ### Tools
 
@@ -106,16 +125,18 @@ Import via Settings → Skills → Import from GitHub (or upload the folder). Ho
 | --- | --- |
 | `auth_status` | Login state, API URL, active org (never the token) |
 | `organization_list` / `organization_set` | Choose organization (`organization_set` needs `confirm=true`) |
+| `list_skills` / `get_skill` | Bundled playbooks (e.g. `.molx`); no login required |
 | `list_files` | Browse a remote path; returns `file_id` + `relative_path` |
 | `pull` / `push` | Transfer with `dry_run` (default true); real transfers need `confirm_transfer=true` |
-| `list_workflows` | Allowlisted agent workflows (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, `msa-generation`) |
+| `list_workflows` | Allowlisted agent workflows (`rf-diffusion3`, `rfd4-proteina`, `proteinmpnn`, `refolding`, `structure-prediction`, `msa-generation`) |
 | `get_workflow_schema` | Full schema with UI-matching defaults |
 | `prepare_workflow_submission` | Merge defaults + overrides; **no submit** (draft body) |
 | `submit_workflow` | Same merge, then submit |
-| `inspect_studio` | Inspect supported `.studio` (proteinmpnn / refolding / rf-diffusion3 / structure_prediction); normalized rows + scores |
+| `inspect_studio` | Inspect supported `.studio` (proteinmpnn / refolding / rf-diffusion3 / rfd4-proteina / structure_prediction); normalized rows + scores |
 | `save_selected_studio` | Same as Studio Save selected → subset `.studio` uploaded + retention finalized (not yet for structure_prediction) |
 | `inspect_proteinmpnn_studio` | Legacy ProteinMPNN flat-row inspect (prefer `inspect_studio`) |
 | `prepare_refolding_from_proteinmpnn_studio` | Build refolding payload + SA handoff from MPNN studio selection (**no submit**) |
+| `list_executions` | List/filter past runs (`workflow_name`, `status`, `output_folder`); includes `design_count` totals |
 | `get_execution` / `list_execution_results` / `cancel_execution` | Status / results / cancel (`cancel_execution` needs `confirm=true`) |
 | `estimate_workflow_cost` | Cost estimate from merged params (same validation as prepare) |
 

{proteworks-0.1.10 → proteworks-0.1.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proteworks"
-version = "0.1.10"
+version = "0.1.11"
 description = "Sync files with Proteworks using file-browser paths."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,5 +25,8 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+proteworks = ["skills/**/*"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{proteworks-0.1.10 → proteworks-0.1.11}/src/proteworks/__init__.py

@@ -8,6 +8,6 @@ try:
     try:
         __version__ = version("proteworks")
     except PackageNotFoundError:
-        __version__ = "0.1.10"
+        __version__ = "0.1.11"
 except Exception:  # pragma: no cover
-    __version__ = "0.1.10"
+    __version__ = "0.1.11"

{proteworks-0.1.10 → proteworks-0.1.11}/src/proteworks/api.py

@@ -209,6 +209,47 @@ class ApiClient:
             data={"name": name, "parent_id": parent_id},
         )
 
+    def get_recycle_bin_folder(self) -> dict:
+        """GET /api/v1/folders/recycle-bin (current user's recycle bin)."""
+        return self.request("GET", "/api/v1/folders/recycle-bin")
+
+    def get_directory(
+        self,
+        folder_id: str,
+        *,
+        files_limit: int = 1,
+        folders_limit: int = 1,
+    ) -> dict:
+        """GET /api/v1/directory/{folder_id} (includes view_in_recycle_bin)."""
+        return self.request(
+            "GET",
+            f"/api/v1/directory/{folder_id}",
+            params={
+                "files_limit": files_limit,
+                "folders_limit": folders_limit,
+                "fields": "summary",
+            },
+        )
+
+    def move_files_to_recycle_bin(self, file_ids: list[str]) -> dict:
+        """POST /api/v1/files/move-to-recycle-bin (soft-delete; not permanent)."""
+        return self.request(
+            "POST",
+            "/api/v1/files/move-to-recycle-bin",
+            json_body={"file_ids": list(file_ids)},
+        )
+
+    def move_folder_to_recycle_bin(self, folder_id: str) -> dict:
+        """POST /api/v1/folders/{id}/move-to-recycle-bin (async job for trees)."""
+        return self.request(
+            "POST",
+            f"/api/v1/folders/{folder_id}/move-to-recycle-bin",
+        )
+
+    def get_folder_recycle_move_job(self, job_id: str) -> dict:
+        """GET /api/v1/folders/recycle-move-jobs/{job_id}."""
+        return self.request("GET", f"/api/v1/folders/recycle-move-jobs/{job_id}")
+
     def upload_init(
         self,
         filename: str,
@@ -414,9 +455,53 @@ class ApiClient:
     def get_agent_schema(self, workflow_name: str) -> dict:
         return self.request("GET", f"/api/v1/workflows/agent-schemas/{workflow_name}")
 
+    def resolve_structure_prediction_methods(
+        self,
+        *,
+        parameters: Optional[dict] = None,
+        complex_ir: Optional[dict] = None,
+        enable_all_capable: bool = False,
+    ) -> dict:
+        """POST capable-predictor resolution for structure-prediction prepare."""
+        body: dict[str, Any] = {"enable_all_capable": bool(enable_all_capable)}
+        if parameters is not None:
+            body["parameters"] = parameters
+        if complex_ir is not None:
+            body["complex_ir"] = complex_ir
+        return self.request(
+            "POST",
+            "/api/v1/workflows/agent-schemas/structure-prediction/resolve-methods",
+            json_body=body,
+        )
+
     def submit_workflow(self, body: dict) -> dict:
         return self.request("POST", "/api/v1/workflows/submit", json_body=body)
 
+    def list_executions(
+        self,
+        *,
+        limit: int = 50,
+        since: Optional[str] = None,
+        workflow_name: Optional[str] = None,
+        status: Optional[str] = None,
+        output_folder: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> list:
+        """GET /api/v1/workflows/executions with optional filters."""
+        params: dict[str, Any] = {"limit": int(limit)}
+        if since:
+            params["since"] = since
+        if workflow_name:
+            params["workflow_name"] = workflow_name
+        if status:
+            params["status"] = status
+        if output_folder:
+            params["output_folder"] = output_folder
+        if user_id:
+            params["user_id"] = user_id
+        payload = self.request("GET", "/api/v1/workflows/executions", params=params)
+        return list(payload or [])
+
     def get_execution(self, execution_id: str) -> dict:
         return self.request("GET", f"/api/v1/workflows/executions/{execution_id}")
 

{proteworks-0.1.10 → proteworks-0.1.11}/src/proteworks/auth.py

@@ -28,20 +28,33 @@ def pkce_pair() -> tuple[str, str]:
     return verifier, challenge
 
 
-def authorize_url(settings: Settings, redirect_uri: str, state: str, challenge: str) -> str:
-    query = urlencode(
-        {
-            "response_type": "code",
-            "client_id": settings.auth0_client_id,
-            "redirect_uri": redirect_uri,
-            "scope": "openid profile email",
-            "audience": settings.auth0_audience,
-            "state": state,
-            "code_challenge": challenge,
-            "code_challenge_method": "S256",
-        }
-    )
-    return f"https://{settings.auth0_domain}/authorize?{query}"
+def authorize_url(
+    settings: Settings,
+    redirect_uri: str,
+    state: str,
+    challenge: str,
+    *,
+    prompt: str | None = "login",
+) -> str:
+    """Build the Auth0 authorize URL.
+
+    ``prompt=login`` (the default) forces the credentials UI even when the browser
+    already has an Auth0 SSO cookie, so ``proteworks login`` can switch accounts.
+    Pass ``prompt=None`` only in tests that need the silent SSO path.
+    """
+    params: dict[str, str] = {
+        "response_type": "code",
+        "client_id": settings.auth0_client_id,
+        "redirect_uri": redirect_uri,
+        "scope": "openid profile email",
+        "audience": settings.auth0_audience,
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    if prompt:
+        params["prompt"] = prompt
+    return f"https://{settings.auth0_domain}/authorize?{urlencode(params)}"
 
 
 class _CallbackHandler(BaseHTTPRequestHandler):
@@ -84,8 +97,29 @@ def open_browser(url: str) -> bool:
         os.close(saved_stderr)
 
 
-def login(settings: Settings, token_store: TokenStore, stderr) -> None:
-    """Open a browser, receive the loopback redirect, and save the access token."""
+def logout(token_store: TokenStore, stderr) -> None:
+    """Forget the local access token (keychain + credentials file)."""
+    token_store.clear()
+    print("Signed out.", file=stderr)
+
+
+def login(settings: Settings, token_store: TokenStore, stderr, *, force: bool = False) -> None:
+    """Open a browser, receive the loopback redirect, and save the access token.
+
+    Always requests ``prompt=login`` so Auth0 does not silently reuse a browser SSO
+    session. With ``force=True``, also clear any local token first and open Auth0's
+    logout endpoint so federated IdP cookies (e.g. Google) do not auto-pick the
+    previous account.
+    """
+    if force:
+        token_store.clear()
+        logout_url = (
+            f"https://{settings.auth0_domain}/v2/logout?"
+            + urlencode({"client_id": settings.auth0_client_id})
+        )
+        print("Clearing the browser Auth0 session…", file=stderr)
+        open_browser(logout_url)
+
     verifier, challenge = pkce_pair()
     state = secrets.token_urlsafe(24)
     try:
@@ -95,8 +129,10 @@ def login(settings: Settings, token_store: TokenStore, stderr) -> None:
             f"Port {LOOPBACK_PORT} is in use, so login cannot listen on {loopback_redirect_uri()}. ({exc})"
         ) from exc
     redirect_uri = loopback_redirect_uri()
-    url = authorize_url(settings, redirect_uri, state, challenge)
+    url = authorize_url(settings, redirect_uri, state, challenge, prompt="login")
     print("Opening a browser to sign in.", file=stderr)
+    if force:
+        print("Choose the account you want, then continue.", file=stderr)
     opened = open_browser(url)
     if not opened:
         print("Open this URL to sign in:", file=stderr)

{proteworks-0.1.10 → proteworks-0.1.11}/src/proteworks/cli.py

@@ -3,12 +3,13 @@
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from pathlib import Path
 
 from proteworks import __version__
 from proteworks.api import ApiClient, ApiError
-from proteworks.auth import login
+from proteworks.auth import login, logout
 from proteworks.config import ConfigStore, Settings, TokenStore, load_settings
 from proteworks.mcp_host import (
     SYSTEM_BIN_DIR_DEFAULT,
@@ -24,9 +25,11 @@ from proteworks.orgs import (
     regular_organizations,
     select_organization,
 )
+from proteworks.executions import summarize_execution_list
 from proteworks.folders import mkdir_remote
 from proteworks.pull import export_organization, pull_path
 from proteworks.push import push_paths
+from proteworks.recycle import RecycleError, recycle_remote
 from proteworks.redact import install_redacting_logs
 from proteworks.session import SessionError, authenticated_client, open_session
 
@@ -50,6 +53,13 @@ examples:
   proteworks mkdir '~/My Files/campaigns/round6/'
 """
 
+_RECYCLE_EXAMPLES = """\
+examples:
+  proteworks recycle '~/My Files/campaigns/run/design.cif'
+  proteworks recycle '~/My Files/campaigns/old-run/'
+  proteworks recycle '~/My Files/msa/*.cif' --dry-run
+"""
+
 _EXPORT_EXAMPLES = """\
 examples:
   proteworks export ./backup
@@ -61,6 +71,13 @@ examples:
   proteworks mcp doctor
 """
 
+_EXECUTIONS_EXAMPLES = """\
+examples:
+  proteworks executions list --workflow-name rf-diffusion3 --status Succeeded
+  proteworks executions list --workflow-name rfd4-proteina,rf-diffusion3 --output-folder 'TFR/'
+  proteworks executions list --output-folder '~/My Files/TFR/' --status Succeeded --limit 200
+"""
+
 
 def build_parser() -> argparse.ArgumentParser:
     """Build the parser, then describe commands by walking what was registered."""
@@ -76,7 +93,16 @@ def build_parser() -> argparse.ArgumentParser:
     )
     sub = parser.add_subparsers(dest="command", required=True)
 
-    sub.add_parser("login", help="Sign in and save an access token in the OS keychain")
+    login_parser = sub.add_parser(
+        "login",
+        help="Sign in and save an access token in the OS keychain",
+    )
+    login_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Clear local credentials and the browser Auth0 session, then sign in (use to switch accounts)",
+    )
+    sub.add_parser("logout", help="Forget the local access token")
 
     org = sub.add_parser("organization", help="List organizations or choose the active one")
     org_sub = org.add_subparsers(dest="org_command", required=True)
@@ -129,6 +155,22 @@ def build_parser() -> argparse.ArgumentParser:
     )
     mkdir.add_argument("remote", help="Remote folder path ending with /")
 
+    recycle = sub.add_parser(
+        "recycle",
+        help="Move a remote file, folder/, or wildcard into the recycle bin (soft delete)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_RECYCLE_EXAMPLES,
+    )
+    recycle.add_argument(
+        "remote",
+        help="File-browser path such as '~/My Files/run/design.cif' or '~/My Files/run/'. Quote wildcards.",
+    )
+    recycle.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would be moved without calling the recycle-bin API",
+    )
+
     export = sub.add_parser(
         "export",
         help="Download the active organization's files (organization admins)",
@@ -138,6 +180,50 @@ def build_parser() -> argparse.ArgumentParser:
     export.add_argument("dest", help="Local directory")
     export.add_argument("--dry-run", action="store_true", help="Print the files that would be downloaded")
 
+    executions = sub.add_parser(
+        "executions",
+        help="List past workflow executions",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_EXECUTIONS_EXAMPLES,
+    )
+    executions_sub = executions.add_subparsers(dest="executions_command", required=True)
+    executions_list = executions_sub.add_parser(
+        "list",
+        help="List executions (filter by workflow name, status, output folder)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_EXECUTIONS_EXAMPLES,
+    )
+    executions_list.add_argument(
+        "--workflow-name",
+        help=(
+            "Workflow name prefix (comma-separated). "
+            "rf-diffusion3 matches rf-diffusion3 and rf-diffusion3-modal."
+        ),
+    )
+    executions_list.add_argument(
+        "--status",
+        help="Status filter (comma-separated), e.g. Succeeded",
+    )
+    executions_list.add_argument(
+        "--output-folder",
+        help="Output folder path prefix, e.g. TFR/ or '~/My Files/TFR/'",
+    )
+    executions_list.add_argument(
+        "--since",
+        help="Only executions updated since this ISO 8601 timestamp",
+    )
+    executions_list.add_argument(
+        "--limit",
+        type=int,
+        default=50,
+        help="Max executions to return (default 50, max 200)",
+    )
+    executions_list.add_argument(
+        "--json",
+        action="store_true",
+        help="Print full JSON summary instead of a table",
+    )
+
     mcp = sub.add_parser(
         "mcp",
         help="System install and local MCP helpers (doctor, optional Science setup)",
@@ -200,7 +286,9 @@ def build_parser() -> argparse.ArgumentParser:
         "  proteworks push '*.pdb' '~/My Files/pdbs/'\n"
         "  proteworks push designs.zip '~/My Files/dest/'\n"
         "  proteworks mkdir '~/My Files/campaigns/round6/'\n"
+        "  proteworks recycle '~/My Files/campaigns/old-run/'\n"
         "  proteworks export ./backup\n"
+        "  proteworks executions list --workflow-name rf-diffusion3 --status Succeeded\n"
         "  sudo proteworks mcp install-system\n"
         "  proteworks mcp doctor\n"
     )
@@ -230,12 +318,15 @@ def main(argv: list[str] | None = None, *, settings: Settings | None = None, tok
     if settings.api_url_overridden:
         print(f"using {settings.api_url}", file=sys.stderr)
     if args.command == "login":
-        login(settings, token_store, sys.stderr)
+        login(settings, token_store, sys.stderr, force=bool(args.force))
         config = ConfigStore(settings.config_dir / "config.json")
         data = config.read()
         data["api_url"] = settings.api_url
         config.write(data)
         return 0
+    if args.command == "logout":
+        logout(token_store, sys.stderr)
+        return 0
     if args.command == "organization" and args.org_command == "list":
         auth = authenticated_client(settings=settings, token_store=token_store)
         if isinstance(auth, SessionError):
@@ -305,6 +396,20 @@ def main(argv: list[str] | None = None, *, settings: Settings | None = None, tok
             action = "created" if result.get("created") else "exists"
             print(f"{action} {result.get('path')} folder_id={result.get('folder_id')}", file=sys.stderr)
             return 0
+        if args.command == "recycle":
+            try:
+                recycle_remote(
+                    session.api,
+                    args.remote,
+                    dry_run=bool(args.dry_run),
+                    stderr=sys.stderr,
+                )
+            except (ApiError, RecycleError, ValueError) as exc:
+                print(str(exc), file=sys.stderr)
+                return 1
+            return 0
+        if args.command == "executions" and args.executions_command == "list":
+            return _executions_list(session.api, args, sys.stdout, sys.stderr)
         parser.print_help(sys.stderr)
         return 2
     finally:
@@ -359,5 +464,51 @@ def _organization_set(api: ApiClient, config: ConfigStore, settings: Settings, n
     return 0
 
 
+def _executions_list(api: ApiClient, args: argparse.Namespace, stdout, stderr) -> int:
+    limit = max(1, min(int(args.limit), 200))
+    try:
+        executions = api.list_executions(
+            limit=limit,
+            since=args.since,
+            workflow_name=args.workflow_name,
+            status=args.status,
+            output_folder=args.output_folder,
+        )
+    except ApiError as exc:
+        print(str(exc), file=stderr)
+        return 1
+    summary = summarize_execution_list(
+        [row for row in executions if isinstance(row, dict)]
+    )
+    if args.json:
+        print(json.dumps(summary, indent=2, default=str), file=stdout)
+        return 0
+    rows = summary.get("executions") or []
+    if not rows:
+        print("No executions matched.", file=stderr)
+        return 0
+    for row in rows:
+        designs = row.get("design_count")
+        designs_s = str(designs) if designs is not None else "?"
+        folder = row.get("output_folder") or "-"
+        print(
+            f"{row.get('created_at') or '-'}  {row.get('status') or '-':12}  "
+            f"{row.get('workflow_name') or '-':22}  designs={designs_s:<6}  "
+            f"id={row.get('id')}  out={folder}",
+            file=stdout,
+        )
+    by_wf = summary.get("by_workflow") or {}
+    total = summary.get("total_designs")
+    print("", file=stderr)
+    for name, bucket in sorted(by_wf.items()):
+        print(
+            f"{name}: {bucket.get('runs', 0)} runs, {bucket.get('designs', 0)} designs",
+            file=stderr,
+        )
+    if total is not None:
+        print(f"total designs: {total}", file=stderr)
+    return 0
+
+
 if __name__ == "__main__":
     raise SystemExit(main())