expedait-cli 0.4.3

CLI for Expedait project management — read and write deliverables, processes, roles, and comments

Expedait CLI

CLI for Expedait — lets AI coding agents download project specs and post comments via the Expedait API.

📖 User docs: app.expedait.org/docs/cli

Table of Contents

• The model
• Installation
• Quickstart
• Project Setup
• Authentication
• Commands
• Agent Skills
• Development
• Getting Help
• Contributing
• License

The model

Expedait organizes specs around four primitives:

• Objectives — top-level goals. An objective is itself a deliverable that nests child deliverables beneath it (parent_deliverable_id).
• Deliverables — the individual spec documents (formerly "pages").
• Context — the assembled LLM context for one deliverable: dependency deliverables, linked external sources, uploaded files, and aggregate sizes.
• Review — scoring findings raised on a deliverable: severity, description, the criteria that flagged them, and anchor offsets.

Installation

Requires Python 3.11+.

Run with uvx (recommended)

No install needed — uvx fetches and runs the CLI on demand, always at the latest version:

uvx expedait-cli --help

With uvx you invoke commands as uvx expedait-cli <command>. The methods below install an expedait executable so you can drop the prefix and run expedait <command> (the form used throughout this README).

Install globally

uv tool install expedait-cli      # via uv — isolated, recommended
pipx install expedait-cli         # via pipx — isolated
pip install expedait-cli          # via pip

uv tool install and pipx keep the CLI in its own virtual environment so it never conflicts with other Python packages — the recommended way to install a standalone CLI.

Add as a project dependency

For an AI agent that needs the CLI available in the project environment:

uv add --group dev expedait-cli

Then reference it in your agent configuration (e.g. CLAUDE.md, .cursor/rules).

Quickstart

expedait auth login          # 1. Authenticate (SSO or email/password)
expedait init                # 2. Store tenant + project for this directory
expedait projects download   # 3. Pull all deliverables into .expedait/context/

Every command and subcommand supports --help:

expedait --help
expedait deliverables --help
expedait deliverables create --help

Project Setup

After authenticating, run init inside your project directory to store your tenant and project settings locally:

uvx expedait-cli init

This creates .expedait/settings.json with your tenant_id and project_id. Add .expedait/ to your .gitignore.

Once initialized, commands that need a project ID will resolve it automatically. Downloads default to .expedait/context/:

expedait projects download              # downloads to .expedait/context/
expedait deliverables list              # no --project-id needed
expedait deliverables download 42       # downloads to .expedait/context/

Resolution order for tenant/project: CLI flag > env var > .expedait/settings.json > ~/.expedait/config.json.

Authentication

Interactive login

uvx expedait-cli auth login

Prompts for login method (SSO or email/password). Stores credentials in ~/.expedait/config.json.

Environment variables (CI / agents)

export EXPEDAIT_TOKEN="your-jwt-token"
export EXPEDAIT_API_URL="https://your-instance.expedait.org"
export EXPEDAIT_TENANT_ID=1

Token resolution order: EXPEDAIT_TOKEN env var > ~/.expedait/config.json > error.

Commands

Auth

expedait auth login       # Interactive login
expedait auth status      # Show current user and tenant
expedait auth logout      # Clear stored credentials

Projects

expedait projects list                       # List all projects
expedait projects get PROJECT_ID             # Get project details
expedait projects workspace PROJECT_ID       # Deliverables grouped by phase (structure-aware view)
expedait projects download PROJECT_ID        # Extract all deliverables to .expedait/context/
expedait projects download PROJECT_ID --output-dir ./specs  # Extract to a custom directory

Writing projects

A project is one instantiation of a process (project type) — the concrete workspace whose deliverables an agent authors. Mirrors the MCP write_project tool. Find the --process-id with expedait processes list.

expedait projects create --name "Q3 Launch" --process-id 3 \  # Create from a process
  [--description "the thing"]
expedait projects update PROJECT_ID --name "New name" \        # Update name/description/process/repo
  [--process-id 4] [--repo-url https://github.com/org/repo]
expedait projects delete PROJECT_ID                            # Preview the cascade (deletes nothing)
expedait projects delete PROJECT_ID --confirm                  # Actually delete
expedait projects write --ops @ops.json                        # Batch (create/update/delete)

Deleting is irreversible and cascades to every deliverable, version, file, comment, and agent run under the project. Because the API deletes immediately with no server-side confirm, the CLI enforces a two-step guard: a bare delete prints what would be destroyed and touches nothing; --confirm (or a delete_project op carrying "confirm": true) is required to proceed.

write --ops ops: create_project, update_project, delete_project. Ops chain via named refs ("ref": "x" on a create, "@x" later) or "$last":

// ops.json
[
  {"op": "create_project", "ref": "p", "name": "Q3 Launch", "project_type_id": 3},
  {"op": "update_project", "id": "@p", "description": "seeded from process 3"}
]

Deliverables

expedait deliverables list --project-id PROJECT_ID   # List deliverables in a project
expedait deliverables types                           # List deliverable types (find the --type ID for create)
expedait deliverables get DELIVERABLE_ID             # Print deliverable markdown content
expedait deliverables get DELIVERABLE_ID --include meta,content,dependencies,score
expedait deliverables inspect DELIVERABLE_ID         # Full context (content + comments + deps + lock)
expedait deliverables download DELIVERABLE_ID        # Extract to .expedait/context/

--include accepts a comma-separated subset of: meta, content, template, requirements, writer_instructions, dependencies, external_context, score, comments, versions. It defaults to content. meta surfaces parent_deliverable_id (non-null ⇒ this deliverable is a child nested under an objective).

Writing deliverables

Mirrors the MCP write_deliverable tool. Ergonomic subcommands cover the common cases; write --ops applies an ordered batch in one call.

expedait deliverables create --project P --type TYPE_ID --title "Vision" \
  [--content @vision.md] [--parent-deliverable-id ID]   # create (content: @file, - for stdin, or literal)
expedait deliverables edit DELIVERABLE_ID --content @body.md   # replace content (autosave, no version bump)
expedait deliverables rename DELIVERABLE_ID --title "New title" # rename without touching content
expedait deliverables save-version DELIVERABLE_ID --reason "checkpoint"  # explicit snapshot
expedait deliverables set-state DELIVERABLE_ID --state "Review"          # transition workflow state

Valid states: Not Started, In Progress, Review, Approved, Completed, Final.

For multi-step writes, write --ops takes a JSON ops array (@file.json, - for stdin, or inline). Each op is one of create, edit, rename, save_version, set_state. Chain ops on a freshly-created deliverable with "id": "$last" (the previous op's deliverable) or bind a name on create ("ref": "x") and reference it later as "id": "@x":

expedait deliverables write --ops @ops.json
# ops.json:
# [
#   {"op": "create", "ref": "v", "project_id": 1, "deliverable_type_id": 3, "title": "Vision"},
#   {"op": "edit", "id": "@v", "content": "# Product Vision\n..."},
#   {"op": "set_state", "id": "@v", "state": "Review"}
# ]

Ops run in order and stop on the first failure (the rest report skipped); the output reports per-op {status: ok | error | skipped}, and the command exits non-zero if any op failed.

Objectives

expedait objectives overview DELIVERABLE_ID   # Objective metadata + full descendant tree

Context

expedait context get DELIVERABLE_ID           # The LLM context snapshot for one deliverable

A deliverable's (or objective's) context is built from dependency deliverables, linked external sources, and uploaded context files. The CLI manages the file half of that surface — attach reference docs an agent should write against, and toggle whether each one feeds the LLM context:

expedait context files DELIVERABLE_ID                 # List attached context files
expedait context add DELIVERABLE_ID ./reference.md    # Upload a context file (re-upload by name replaces)
expedait context file-content FILE_ID                 # Parsed text the file contributes to context
expedait context download-file FILE_ID -o ./out.md    # Download a file's raw bytes
expedait context set-file FILE_ID --exclude           # Exclude from LLM context (or --include)
expedait context remove-file FILE_ID                  # Delete a context file

External source links (Notion, GitHub, etc.) are created through the web app's integration flows, not the CLI.

Review

expedait review issues DELIVERABLE_ID                 # List scoring findings (default: all)
expedait review issues DELIVERABLE_ID --state open    # Only open findings
expedait review mute ISSUE_ID --note "by design"      # Mute a finding
expedait review mute ISSUE_ID --unmute                # Unmute a finding

Comments

expedait comments list DELIVERABLE_ID                 # List comments on a deliverable
expedait comments create DELIVERABLE_ID \             # Create a comment (offsets resolved automatically)
  --text "Comment content" \
  --selected-text "text from the deliverable" \
  --source-deliverable-id 5                            # Optional: agent's source deliverable
expedait comments resolve DELIVERABLE_ID COMMENT_ID   # Mark as resolved
expedait comments delete DELIVERABLE_ID COMMENT_ID    # Delete a comment

Only --text and --selected-text are required; the CLI locates the selected text in the deliverable to compute anchor offsets. Pass --start-offset and --end-offset to anchor explicitly (e.g. when the selected text appears more than once).

Processes (Process Designer)

A process is a project type plus the template tree it owns: phases → rows → deliverable-type cards, dependency edges, owner roles, and objective subprocesses. Editing it reshapes every project instantiated from it. Mirrors the MCP list_processes / get_process / write_process tools.

expedait processes list                   # List processes (project types)
expedait processes get PROCESS_ID         # Full template tree (phases, rows, cards, roles)
expedait processes write --ops @ops.json  # Build or adapt a process in one call

write --ops ops: create_process, update_process, duplicate_process, delete_process, create_phase, update_phase, delete_phase, create_phase_row, update_phase_row, delete_phase_row, create_deliverable_type, update_deliverable_type, delete_deliverable_type, set_dependencies, set_owner_roles. Ops chain via named refs ("ref": "x" on a create op, "@x" later). Card layout is optional — omit col_position and cards auto-place (append, or just after after_type_id). set_owner_roles accepts role names or ids. Delete ops refuse an in-use template unless the op carries "confirm_in_use": true.

// ops.json — build a process end to end in one call
[
  {"op": "create_process", "ref": "p", "name": "Product Dev"},
  {"op": "create_phase", "ref": "ph", "process_id": "@p", "name": "Discovery"},
  {"op": "create_deliverable_type", "ref": "vision", "phase_id": "@ph", "name": "Vision"},
  {"op": "create_deliverable_type", "ref": "prd", "phase_id": "@ph", "name": "PRD", "after_type_id": "@vision"},
  {"op": "set_dependencies", "type_id": "@prd", "dependency_ids": ["@vision"]},
  {"op": "set_owner_roles", "type_id": "@prd", "role_names": ["Product Manager"]}
]

Roles

A role is a workspace project role — the owner-role pool assigned to deliverable types. A role's instructions is its LLM coaching persona. Mirrors the MCP list_roles / write_role tools.

expedait roles list                                       # List project roles
expedait roles create --name "Product Manager" \          # Create (instructions: @file, -, or literal)
  [--description "owns the roadmap"] [--instructions @pm.md]
expedait roles update ROLE_ID --name "Lead PM"            # Update name/description/instructions
expedait roles delete ROLE_ID                             # Delete a role
expedait roles write --ops @ops.json                      # Batch (create_role/update_role/delete_role)

Global Options

expedait --api-url https://host:8000 ...    # Override API URL
expedait --tenant-id 2 ...                  # Override tenant
expedait --format json ...                  # Force JSON output
expedait --format text ...                  # Force human-readable output
expedait --version                          # Show version

Output format defaults to text when connected to a terminal, json when piped.

Migration note: the pages command group has been renamed to deliverables. expedait pages … still works for one release (it warns and forwards) but will be removed.

Agent Skills

For step-by-step guides on using the CLI from AI coding agents, see expedait-skills.

Development

git clone https://github.com/Expedait/expedait-cli.git
cd expedait-cli
uv sync --group dev
uv run python -m pytest

Getting Help

• Read the user documentation for a guided walkthrough.
• Run expedait <command> --help for terminal reference on any command.
• Found a bug or have a feature request? Open an issue.

Contributing

Contributions are welcome. Set up the project as shown in Development, make your change with tests, and open a pull request against main. CI runs the test suite on Python 3.11–3.13.

License

Apache License 2.0