Command Reference

Complete reference for all Stardust CLI commands. Use stardust --help to see this list in your terminal.

Command Groups

task - Single task operations
tasks - List and filter multiple tasks
add - Quick task capture
git - Git operations (gitoxide-powered)
file - File search and analysis
cache - Cache management

task

Manage individual tasks.

task create

Create a new task.

stardust task create <TITLE> [OPTIONS]

Arguments:

TITLE - Task title (natural language supported)

Options:

--priority TEXT - Priority: critical, high, medium, low (default: medium)
--due TEXT - Due date (e.g., “tomorrow”, “next Monday”, “2025-01-15”)
--tags TEXT - Comma-separated tags
--description TEXT - Additional context

Examples:

# Simple task
stardust task create "Review the API documentation"

# With priority
stardust task create "Fix auth bug" --priority high

# With due date and tags
stardust task create "Update landing page" --due "Friday" --tags marketing,urgent

# Natural language (AI parses intent)
stardust task create "Follow up with Sarah after her PTO about the roadmap"

task start

Mark a task as in progress.

stardust task start <TASK_ID>

Arguments:

TASK_ID - Task ID (e.g., tk-001)

Example:

stardust task start tk-001

Only have one task in progress at a time. Finish before starting another.

task done

Mark a task as completed.

stardust task done <TASK_ID>

Arguments:

TASK_ID - Task ID

Example:

stardust task done tk-001

task update

Update task details.

stardust task update <TASK_ID> [OPTIONS]

Arguments:

TASK_ID - Task ID

Options:

--title TEXT - New title
--priority TEXT - New priority
--due TEXT - New due date
--status TEXT - Status: todo, in_progress, blocked, done
--tags TEXT - Replace tags
--add-tag TEXT - Add a tag
--description TEXT - Update description

Examples:

# Change priority
stardust task update tk-001 --priority critical

# Mark as blocked
stardust task update tk-001 --status blocked --description "Waiting on API key"

# Add a tag
stardust task update tk-001 --add-tag needs-review

task delete

Delete a task.

stardust task delete <TASK_ID> [OPTIONS]

Arguments:

TASK_ID - Task ID

Options:

--force - Skip confirmation prompt

Example:

stardust task delete tk-001

# Skip confirmation
stardust task delete tk-001 --force

Strategic Laziness: Don’t be afraid to delete tasks. The best work is the work you don’t do.

task show

Show task details.

stardust task show <TASK_ID>

Arguments:

TASK_ID - Task ID

Example:

stardust task show tk-001

Output:

Task: tk-001
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title:       Review API documentation
Status:      in_progress
Priority:    high
Due:         Tomorrow
Tags:        docs, api
Created:     2 days ago
Owner:       you

Description:
Go through the new endpoints and update examples.

tasks

List and filter multiple tasks.

tasks ready

Show tasks ready to work on (not blocked).

stardust tasks ready [OPTIONS]

Options:

--owner TEXT - Filter by owner (@me for your tasks)
--priority TEXT - Filter by priority (comma-separated)
--tags TEXT - Filter by tags
--limit INTEGER - Max results (default: 20)
--json - Output as JSON

Examples:

# Your ready tasks
stardust tasks ready --owner @me

# High priority only
stardust tasks ready --priority high,critical

# With tag filter
stardust tasks ready --tags api --limit 5

# JSON output for scripting
stardust tasks ready --json

tasks list

List all tasks (including blocked).

stardust tasks list [OPTIONS]

Options:

--status TEXT - Filter by status: todo, in_progress, blocked, done
--owner TEXT - Filter by owner
--priority TEXT - Filter by priority
--due-before TEXT - Due before date (e.g., “tomorrow”, “end of week”)
--limit INTEGER - Max results
--json - Output as JSON

Examples:

# All in-progress tasks
stardust tasks list --status in_progress

# Tasks due this week
stardust tasks list --due-before "end of week"

# Blocked tasks
stardust tasks list --status blocked

tasks prioritize

Get AI-powered priority recommendations.

stardust tasks prioritize [OPTIONS]

Options:

--owner TEXT - Filter by owner (default: @me)
--json - Output as JSON

Example:

stardust tasks prioritize

Output:

AI Priority Recommendations
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Do Now
│ Fix auth bug (tk-002)
│ Reason: Critical priority, due today, blocks 3 other tasks

Do Next
│ Review API docs (tk-001)
│ Reason: High priority, due tomorrow, required for release

Consider Deleting
│ Reorganize file structure (tk-010)
│ Reason: Low priority, no due date, untouched for 3 months

tasks next

Show the single most important task.

stardust tasks next

Example:

stardust tasks next

Output:

Next Task: tk-002
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix auth bug

Why: Critical priority, due today, blocks 3 other tasks

Run 'stardust task start tk-002' to begin

add

Quick task capture with natural language.

stardust add <TEXT> [OPTIONS]

Arguments:

TEXT - Natural language task description

Options:

--priority TEXT - Override inferred priority

Examples:

# Natural language capture
stardust add "Follow up with Sarah after her PTO"

# With priority override
stardust add "Fix the login bug" --priority critical

# AI parses dates and context
stardust add "Review roadmap before Thursday's meeting"

Use add for quick capture without leaving your workflow. Stardust’s AI extracts due dates, priorities, and context automatically.

git

Git operations powered by gitoxide (no system git required).

git status

Show repository status.

stardust git status [PATH]

Arguments:

PATH - Repository path (default: current directory)

Example:

stardust git status .

git log

Show commit history.

stardust git log [PATH] [OPTIONS]

Arguments:

PATH - Repository path (default: current directory)

Options:

--count INTEGER - Number of commits (default: 10)

Example:

stardust git log . --count 5

file

File search and analysis tools.

file find

Find files by pattern.

stardust file find <PATTERN> [OPTIONS]

Arguments:

PATTERN - Glob pattern (e.g., *.py, src/**/*.ts)

Options:

--path TEXT - Directory to search (default: current directory)
--max INTEGER - Maximum results (default: 100, 0=unlimited)
--json - Output as JSON

Example:

stardust file find "*.py" --path ./src

file grep

Search file contents.

stardust file grep <PATTERN> [OPTIONS]

Arguments:

PATTERN - Regex pattern to search for

Options:

--path TEXT - Directory to search (default: current directory)
--files TEXT - File pattern filter (e.g., *.ts)
--max INTEGER - Maximum results
--json - Output as JSON

Example:

# Find TODOs in TypeScript files
stardust file grep "TODO" --files "*.ts"

# Find function definitions
stardust file grep "function\s+\w+" --path ./src

file loc

Count lines of code.

stardust file loc [OPTIONS]

Options:

--path TEXT - Directory to analyze (default: current directory)

Example:

stardust file loc --path ./src

Output:

Lines of Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Language     Files    Code    Comments    Blanks    Total
──────────   ─────    ────    ────────    ──────    ─────
TypeScript   45       3420    156         412       3988
Python       32       2100    89          298       2487
Rust         8        650     42          78        770
──────────   ─────    ────    ────────    ──────    ─────
TOTAL        85       6170    287         788       7245

file tree

Show directory structure.

stardust file tree [OPTIONS]

Options:

--path TEXT - Directory to show (default: current directory)
--depth INTEGER - Maximum depth (default: 3, 0=unlimited)
--json - Output as JSON

Example:

stardust file tree --depth 2

cache

Manage the CLI’s cache.

cache info

Show cache directory and statistics.

stardust cache info

Example:

stardust cache info

Output:

Cache Directory: /Users/you/Library/Caches/stardust-cli
Cache Entries: 12
Total Size: 1.24 MB

cache clear

Clear all cached data.

stardust cache clear

Example:

stardust cache clear

version

Show CLI version and features.

stardust version

Output:

Stardust CLI v1.0.0
Features: git, cache, file-ops
Powered by Rust + Python

Global Options

These options work with any command:

Option	Description
`--help`	Show help message
`--version`	Show CLI version
`-v, --verbose`	Enable verbose output
`-q, --quiet`	Suppress output except errors
`--json`	Output as JSON (where supported)

Example:

# Verbose mode
stardust -v tasks ready

# Quiet mode
stardust -q task done tk-001

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid usage or arguments

Shell Completion

Enable tab completion:

# Zsh
stardust --install-completion zsh

# Bash
stardust --install-completion bash

# Fish
stardust --install-completion fish

Restart your shell after installation.

Core Features

Desktop App

CLI

Integrations

Command Reference

Command Reference

Command Groups

task

task create

task start

task done

task update

task delete

task show

tasks

tasks ready

tasks list

tasks prioritize

tasks next

add

git

git status

git log

file

file find

file grep

file loc

file tree

cache

cache info

cache clear

version

Global Options

Exit Codes

Shell Completion

Core Features

Desktop App

CLI

Integrations

​Command Reference

​Command Groups

​task

​task create

​task start

​task done

​task update

​task delete

​task show

​tasks

​tasks ready

​tasks list

​tasks prioritize

​tasks next

​add

​git

​git status

​git log

​file

​file find

​file grep

​file loc

​file tree

​cache

​cache info

​cache clear

​version

​Global Options

​Exit Codes

​Shell Completion

Command Reference

Command Groups

task

task create

task start

task done

task update

task delete

task show

tasks

tasks ready

tasks list

tasks prioritize

tasks next

add

git

git status

git log

file

file find

file grep

file loc

file tree

cache

cache info

cache clear

version

Global Options

Exit Codes

Shell Completion