project

Project management commands. Projects are the top-level container for tasks and epics.

Commands

sibyl project list - List all projects
sibyl project show - Show project details
sibyl project create - Create a project
sibyl project progress - Show project progress
sibyl project link - Link directory to project
sibyl project relink - Repair the link for the current directory
sibyl project unlink - Remove directory link
sibyl project links - List all directory links

project list

List all projects.

Synopsis

bash

sibyl project list [options]

Options

Option	Short	Default	Description
`--limit`	`-n`	20	Max results
`--json`	`-j`	false	JSON output
`--csv`		false	CSV output

Example

bash

sibyl project list

Output:

Projects
ID          Name                Status    Description
───────────────────────────────────────────────────────────────────
proj_abc1.. Backend API         active    REST API for mobile and web clients
proj_def2.. Mobile App          active    iOS and Android app
proj_ghi3.. Documentation       active    Technical documentation site

Showing 3 project(s)

project show

Show project details with task summary.

Synopsis

bash

sibyl project show <project_id> [options]

Options

Option	Short	Description
`--json`	`-j`	JSON output

Example

bash

sibyl project show proj_abc123

Output:

Project proj_abc1
  Name:    Backend API
  Status:  active

  Description:
  REST API for mobile and web clients

  Task Summary:
    todo: 12
    doing: 3
    blocked: 1
    review: 2
    done: 45

  Progress: ████████████░░░░░░░░ 71%

  Tech Stack: typescript, express, postgresql

JSON Output

bash

sibyl project show proj_abc123 --json

json

{
  "id": "proj_abc123",
  "name": "Backend API",
  "entity_type": "project",
  "description": "REST API for mobile and web clients",
  "metadata": {
    "status": "active",
    "tech_stack": ["typescript", "express", "postgresql"]
  },
  "task_summary": {
    "total": 63,
    "by_status": {
      "todo": 12,
      "doing": 3,
      "blocked": 1,
      "review": 2,
      "done": 45
    }
  }
}

project create

Create a new project.

Synopsis

bash

sibyl project create --name <name> [options]

Required Options

Option	Short	Description
`--name`	`-n`	Project name (required)

Options

Option	Short	Description
`--description`	`-d`	Project description
`--repo`	`-r`	Repository URL
`--json`	`-j`	JSON output

Example

bash

sibyl project create \
  --name "Backend API" \
  --description "REST API for mobile and web clients" \
  --repo "https://github.com/org/backend-api"

Output:

Project created: proj_abc123def456

project progress

Show project progress with visual breakdown.

Synopsis

bash

sibyl project progress <project_id> [options]

Options

Option	Short	Description
`--json`	`-j`	JSON output

Example

bash

sibyl project progress proj_abc123

Output:

Project Progress

  ████████████████████████████░░░░░░░░░░░░ 71.4% (45/63)

Status Breakdown:
  backlog    ██ 2
  todo       ████████████ 12
  doing      ███ 3
  blocked    █ 1
  review     ██ 2
  done       █████████████████████████████████████████████ 45

JSON Output

bash

sibyl project progress proj_abc123 --json

json

{
  "project_id": "proj_abc123",
  "total_tasks": 63,
  "completed": 45,
  "progress_percent": 71.4,
  "by_status": {
    "backlog": 2,
    "todo": 12,
    "doing": 3,
    "blocked": 1,
    "review": 2,
    "done": 45
  }
}

project link

Link a directory to a project for automatic context. This is the key to automatic project-scoped operations.

Synopsis

bash

sibyl project link <project_id> [options]

Options

Option	Short	Default	Description
`--path`	`-p`	cwd	Directory path to link
`--this-worktree`		off	Inside a git worktree, pin only this worktree (see below)

Example

bash

cd ~/dev/backend-api
sibyl project link proj_abc123

Output:

Linked /home/user/dev/backend-api
  -> Backend API (proj_abc123def456...)
Task commands in this directory will now auto-scope to this project

Link Another Directory

bash

sibyl project link proj_xyz789 --path ~/dev/mobile-app

How It Works

Once linked:

bash

cd ~/dev/backend-api
sibyl task list              # Only shows tasks for proj_abc123
sibyl context "work on auth"  # Only loads context from proj_abc123
sibyl task create --title "Fix bug"  # Creates in proj_abc123

The link is stored in ~/.sibyl/config.toml:

toml

[paths]
"/home/user/dev/backend-api" = "proj_abc123"
"/home/user/dev/mobile-app" = "proj_xyz789"

Git worktrees

Every worktree of a repository routes like the repository. Run sibyl project link inside a git worktree and the link is stored at the equivalent path in the main checkout, so the main checkout and all of its worktrees, current and future, reach the same project and server:

bash

cd ~/dev/worktrees/backend-api/fix-login
sibyl project link proj_abc123
# links ~/dev/backend-api, which every worktree of it uses

If the worktree had its own link, that link is removed, since it would keep overriding the repository's. Pass --this-worktree to pin a single worktree on purpose.

Inside a worktree, a directory resolves its project and server in this order: a link inside the worktree itself, then the equivalent path in the main checkout (so a link on ~/dev/backend-api/apps/web also applies in apps/web of every worktree), then the nearest linked parent directory. The project and the server resolve separately, so a worktree link that names only a project still uses the repository's server.

project relink

Repair the project link for the current directory. Use this when a link points at a stale or renamed project and you want to retarget it without unlinking first.

Synopsis

bash

sibyl project relink [options]

Options

Option	Short	Default	Description
`--id`		(none)	Project ID, UUID, name, or slug to relink to
`--path`	`-p`	cwd	Directory path
`--this-worktree`		off	Inside a git worktree, pin only this worktree

Example

bash

cd ~/dev/backend-api
sibyl project relink --id backend-api

project unlink

Remove project link from a directory.

Synopsis

bash

sibyl project unlink [options]

Options

Option	Short	Default	Description
`--path`	`-p`	cwd	Directory path to unlink

Example

bash

cd ~/dev/backend-api
sibyl project unlink

Output:

Unlinked /home/user/dev/backend-api

Unlink Specific Path

bash

sibyl project unlink --path ~/dev/old-project

Inside a git worktree without a link of its own, unlink removes the repository's link, which every worktree of it uses, and says so.

project links

List all directory-to-project links, or plan a cleanup of them.

Synopsis

bash

sibyl project links [--prune [--apply]]

Options

Option	Default	Description
`--prune`	off	Plan a cleanup of directory links (dry run)
`--apply`	off	With `--prune`, write the planned cleanup

Example

bash

sibyl project links

Output:

Project Links:

* /home/user/dev/backend-api
    -> proj_abc123def456789
  /home/user/dev/mobile-app
    -> proj_xyz789abc123456

* = current context

Cleaning up links

Links made inside worktrees by older CLI versions live on the worktree path, and removed worktrees leave their links behind. --prune plans a cleanup:

Links whose checkout is gone (a removed worktree) and empty links are dropped.
A worktree link the repository's link already implies is dropped.
A worktree link moves onto its repository when the repository has none and every worktree agrees. This deliberately makes the repository and its other worktrees route that way too.
A worktree link that pins something different is kept and reported, with the command to remove it.
A change that would expose a pin higher up in the same worktree is kept and reported.

Apart from lifts, no link's own directory changes where it routes. A directory below a dropped worktree link can start following a deeper link in the repository, which is how the main checkout already routes it.

bash

sibyl project links --prune          # dry run: prints the plan
sibyl project links --prune --apply  # writes it

--apply re-plans under the config lock and refuses if the links changed since the dry run.

Common Workflows

Setup New Project

bash

# 1. Create project
sibyl project create --name "My New Project" --description "Project description"
# Returns: proj_abc123

# 2. Link directory
cd ~/dev/my-new-project
sibyl project link proj_abc123

# 3. Create initial tasks
sibyl task create --title "Setup repository"
sibyl task create --title "Configure CI/CD"
sibyl task create --title "Write initial documentation"

Multi-Project Workflow

bash

# Work on backend
cd ~/dev/backend
sibyl task list --status doing
sibyl task complete task_abc --learnings "..."

# Switch to frontend
cd ~/dev/frontend
sibyl task list --status todo
sibyl task start task_xyz

Cross-Project Operations

bash

# Search across all projects
sibyl context "authentication" --all

# List all tasks (all projects)
sibyl task list --all

# Override the project for a single command
sibyl task list --project proj_other

sibyl task list - List tasks (respects project context)
sibyl config context - Manage named server, org, and project contexts
sibyl epic list - List epics in project

project ​

Commands ​

project list ​

Synopsis ​

Options ​

Example ​

project show ​

Synopsis ​

Options ​

Example ​

JSON Output ​

project create ​

Synopsis ​

Required Options ​

Options ​

Example ​

project progress ​

Synopsis ​

Options ​

Example ​

JSON Output ​

project link ​

Synopsis ​

Options ​

Example ​

Link Another Directory ​

How It Works ​

Git worktrees ​

project relink ​

Synopsis ​

Options ​

Example ​

project unlink ​

Synopsis ​

Options ​

Example ​

Unlink Specific Path ​

project links ​

Synopsis ​

Options ​

Example ​

Cleaning up links ​

Common Workflows ​

Setup New Project ​

Multi-Project Workflow ​

Cross-Project Operations ​

Related Commands ​

project

Commands

project list

Synopsis

Options

Example

project show

Synopsis

Options

Example

JSON Output

project create

Synopsis

Required Options

Options

Example

project progress

Synopsis

Options

Example

JSON Output

project link

Synopsis

Options

Example

Link Another Directory

How It Works

Git worktrees

project relink

Synopsis

Options

Example

project unlink

Synopsis

Options

Example

Unlink Specific Path

project links

Synopsis

Options

Example

Cleaning up links

Common Workflows

Setup New Project

Multi-Project Workflow

Cross-Project Operations

Related Commands