From 6532cba94f2769ee8ce13fc77b27329f6b5c2eca Mon Sep 17 00:00:00 2001 From: typebasedio Date: Fri, 10 Apr 2026 17:02:58 -0400 Subject: [PATCH] docs(v0.3): document new ctask list semantics and --task flag Reflects the v0.3 polish-pass changes: - default 'ctask list' shows active tasks AND projects - --task flag added; --task and --projects are exclusive - output now includes a "type" column - 'ctask last' explicitly notes it considers both types --- docs/commands.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 3e37346..607c883 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -69,39 +69,39 @@ The general seed is applied to every workspace. The project seed is applied **on ## ctask list -Show recent workspaces in reverse-chronological order. +List workspaces in reverse-chronological order. ``` ctask list [flags] ``` +By default, `ctask list` shows **all active workspaces** -- both tasks and projects. Use `--task` or `--projects` to narrow by type, and `--all` to include archived workspaces. + **Flags:** | Flag | Short | Default | Description | |------|-------|---------|-------------| | `--all` | `-a` | off | Include archived workspaces | -| `--projects` | | off | Show project workspaces instead of task workspaces | +| `--task` | | off | Show task workspaces only | +| `--projects` | | off | Show project workspaces only | | `--category` | `-c` | all | Filter by category | | `--limit` | `-n` | 20 | Maximum entries to show | +`--task` and `--projects` are mutually exclusive; passing both returns a usage error. + **Examples:** ```powershell -ctask list -ctask list --all -ctask list --projects -ctask list --projects --all +ctask list # active tasks AND projects +ctask list --all # everything (incl. archived) +ctask list --task # active tasks only +ctask list --task --all # all tasks (incl. archived) +ctask list --projects # active projects only +ctask list --projects --all # all projects (incl. archived) ctask list -c scripts -n 5 ``` -Output columns: status, mode, category, date, slug. - -The `--all` flag controls archived visibility only. The `--projects` flag controls type filtering only. They combine independently: - -- `ctask list` -- active tasks only -- `ctask list --all` -- active + archived tasks -- `ctask list --projects` -- active projects only -- `ctask list --projects --all` -- active + archived projects +Output columns: status, type, mode, category, date, slug. Workspaces created before v0.3 (which have no `type` field in `task.yaml`) are treated as tasks. @@ -209,7 +209,7 @@ To see archived workspaces, use `ctask list --all`. To resolve archived workspac ## ctask last -Resume the most recently updated workspace. Equivalent to `ctask resume` on whichever workspace has the latest `updated_at` timestamp. +Resume the most recently updated workspace, considering **both tasks and projects**. Equivalent to `ctask resume` on whichever active workspace has the latest `updated_at` timestamp. Archived workspaces are excluded. ``` ctask last [flags]