lt - LiteTracker CLI

A command-line tool for interacting with the LiteTracker API. Manage projects, stories, labels, and comments from your terminal.

Install

One-liner:

curl -fsSL https://raw.githubusercontent.com/MelianLabs/litetracker-cli/main/install.sh | bash

Manual:

git clone https://github.com/MelianLabs/litetracker-cli.git
sudo cp litetracker-cli/lt /usr/local/bin/lt

Dependencies: bash, curl, jq, and sqlite3 (only for lt cache commands)

# Ubuntu/Debian
sudo apt install jq sqlite3

# macOS
brew install jq sqlite

Setup

1. Get your API token from https://app.litetracker.com/edit
2. Run:

lt auth

Your token is saved to ~/.lt/api_token.

Usage

Projects

# List all projects
lt projects

Current User

# Show your user details, accounts, and project memberships
lt me

Stories

# List stories in a project (default: first 50)
lt stories <project_id>

# Fetch all stories across pages (the API caps each page at 50)
lt stories <project_id> --all

# Client-side filter by state
lt stories <project_id> --all --state unscheduled

# Manual pagination
lt stories <project_id> --offset 50 --limit 50

# Show story details
lt story show <project_id> <story_id>

# Create a story
lt story create <project_id> --name "Build login page" --type feature --estimate 3 --label "frontend"

# Create a story with description
lt story create <project_id> --name "Fix bug" --type bug --description "Steps to reproduce..."

# Update a story
lt story update <project_id> <story_id> --state "started" --estimate 3 --owner-ids 42,55

# Add a label to a story
lt story label <project_id> <story_id> --label "urgent"

# List comments on a story
lt story comments <project_id> <story_id>

# Add a comment to a story
lt story comment <project_id> <story_id> --text "Working on this now"

Local cache

The LiteTracker API has no server-side filters (no --label, no --state, no updated_since), so any query like "all stories with label X" requires paging through every story 50 at a time. lt cache mirrors one or more projects into a local SQLite database so subsequent queries are instant and incremental.

# Initial sync — pages through /projects/<id>/stories until done
lt cache sync 123456

# Incremental re-sync — only stories whose `updated_at` changed are rewritten
lt cache sync 123456

# Sync several projects at once
lt cache sync 123456 789012

# Also pull /stories/<id> description and /comments for stories that changed
lt cache sync 123456 --with-descriptions --with-comments

# Drop the project's rows before re-inserting (rebuild from scratch)
lt cache sync 123456 --full --quiet

# Resume a sync that died partway (e.g. after a 504 at page 277)
lt cache sync 123456 --start-page 278
lt cache sync 123456 --start-offset 13850   # same thing, expressed as a story offset

# Query the cache — same output shape as `lt stories`, no API calls
lt cache stories 123456 --label failing-spec
lt cache stories 123456 --label failing-spec --state unscheduled
lt cache stories 123456 --type bug --since 2026-04-01T00:00:00Z

# Inspect cache state
lt cache stats
lt cache stats 123456

# Remove cached rows for one project, or wipe the DB entirely
lt cache clear 123456
lt cache clear

Cache layout:

• ~/.lt/cache/litetracker.db — single SQLite file shared across projects.
• Schema embedded inside the lt script (see cache_schema_sql function). On every sync CREATE TABLE IF NOT EXISTS runs first, so it self-heals.
• Diff key: each story's updated_at timestamp. Re-syncs skip rows whose timestamp matches.

GET requests retry on 5xx and network errors with exponential backoff (5 attempts: 1s, 2s, 4s, 8s, 16s — override with LT_API_MAX_ATTEMPTS=N). If a long sync still dies, re-run with --start-page pointing at the page after the last one that succeeded.

Known limitations (intentional for v1):

• Deletions in LT don't propagate locally until --full.
• Sync is sequential (no parallel curl) — initial sync of a 4000-story project takes a few minutes.
• lt stories (the live command) still hits the API; cache reads are explicit via lt cache stories.

Schema

Inspect any API endpoint to see its HTTP method, path, parameters, request body, and response shape:

# List all available endpoints
lt schema

# Show details for a specific endpoint
lt schema stories.create
lt schema stories.comments.list

This is particularly useful for AI agents and LLM-based tools that need to discover which operations are available and how to call them. An agent can run lt schema to enumerate endpoints, then lt schema <endpoint> to get the full parameter and response specification as structured JSON — no docs lookup required.

Other

lt help       # Show help
lt version    # Show version

Examples

# List your projects and pick one
lt projects

# See what stories are in the project
lt stories 123456

# Create a bug report
lt story create 123456 --name "Fix login redirect" --type bug --description "Login redirects to 404"

# Add a label
lt story label 123456 789012 --label "merged-into-main"

# Leave a note
lt story comment 123456 789012 --text "Root cause found - session cookie not set"

Story Types

Types: feature, bug, chore

AI Agent Integration

lt is designed to be used by AI coding agents (Claude Code, Cursor, Copilot, etc.) as a tool for managing project tasks. Agents can:

1. Discover available operations — run lt schema to list all endpoints
2. Inspect any endpoint — run lt schema stories.create to get structured JSON describing the method, path, required/optional parameters, request body shape, and response fields
3. Execute commands — call lt subcommands directly to list projects, read stories and comments, create stories, add labels, etc.

The schema output is machine-readable JSON, so agents can parse it to understand exactly which fields to pass and what to expect back — without needing access to external documentation.

Example prompt in Claude Code:

Look at story 123456 in project abc123, explain the issue in detail, and propose a fix.

The agent will use lt schema to discover available operations, then run lt story show and lt story comments to pull the story details and discussion, and use that context to explain the problem and suggest a solution grounded in the actual conversation.

Uninstall

sudo rm /usr/local/bin/lt
rm -rf ~/.lt

API Reference

LiteTracker REST API v5 Documentation