Timestripe CLI

The official command-line client for the Timestripe.

---

Install

Homebrew (macOS, Linux)

brew install timestripe/tap/timestripe-cli

Upgrade later with:

brew upgrade timestripe-cli

From source

Requires Go 1.26+.

go install github.com/timestripe/timestripe-cli/cmd/timestripe@latest

Or clone and build:

git clone https://github.com/timestripe/timestripe-cli
cd timestripe-cli
make build   # → ./bin/timestripe

Pre-built binaries

Download for macOS or Linux (amd64 / arm64) from the Releases page.

Quick start

timestripe auth login                  # opens your browser
timestripe spaces list
timestripe boards list --space-id <space-id>

# Parent references accept a name or an ID, so you rarely need to look one up:
timestripe add "Ship the thing" --space Work --bucket "This Week" --horizon week --date friday
timestripe goals list --open
timestripe done "Ship the thing"

Every command has --help with full flag and subcommand documentation:

timestripe --help
timestripe goals create --help

Authentication

OAuth authentication with your browser:

timestripe auth login

Request the read-only scope (write operations will fail):

timestripe auth login --read-only

Skip the browser by using a personal api key (manage keys in Settings):

timestripe auth login --token <your-api-key>

Or supply a token per-invocation via env, bypassing stored credentials entirely:

export TIMESTRIPE_TOKEN=<your-api-key> timestripe ...

Related commands:

• timestripe auth whoami — show the authenticated user
• timestripe auth status — verify the stored token still works
• timestripe auth logout — remove stored credentials

AI agents

timestripe works with any AI agent that can run shell commands — --json output is structured, exit codes are stable, and a ready-made skill ships with the repo.

• Claude Code: drop skills/timestripe/ into ~/.claude/skills/ (global) or <your-project>/.claude/skills/ (per-project). Claude loads it automatically when you mention goals, tasks, todos, spaces, or Timestripe.
• Other agents: point the agent at skills/timestripe/SKILL.md. It documents the command surface, JSON envelope, server-side filters, and common recipes.

Commands

Command	Purpose
auth	Log in, log out, inspect the active session
spaces	Manage spaces
boards	Manage boards
buckets	Manage buckets
goals	Manage goals
comments	Manage goal comments
events	Inspect activity events (read-only)
folders	Manage folders and which goals belong to them
memberships	Manage workspace memberships
users	Look up users
config	Show resolved configuration
version	Print version, commit, and build date

Most resource commands expose list, get, create, update, and delete. events, memberships, and users are read-only: they expose list and get only. Run --help on any command for details.

Shortcuts

Quick commands

Command	Same as
timestripe add "Buy milk"	timestripe goals create "Buy milk"
timestripe done <goal>	timestripe goals update <id> --checked
timestripe reopen <goal>	timestripe goals update <id> --checked=false

done and reopen accept a goal name as well as an ID.

Short flags

A letter means the same thing on every command.

Short	Long		Short	Long
-f	--file		-H	--horizon
-n	--name		-d	--date
-s	--space		-q	--search
-b	--bucket		-l	--limit
-a	--assignee		-A	--all

Note that -s is always --space and -q is always --search; -b is always --bucket, never --board.

Names instead of IDs

--space, --bucket, --board, --goal, --folder, --parent, and --assignee all accept a name as well as an ID. An ID always wins if a name happens to collide with one. --assignee also matches an email address or a full name.

If a name is ambiguous, the CLI lists the candidates. In an interactive terminal it prompts you to pick one; when stdin is a pipe or a file it just returns the error, so scripts never block.

Dates

--date (and --date-from, --date-to, --updated-since) accept:

Form	Example
ISO date	2026-09-01
Relative day	today, tomorrow, yesterday
Weekday	friday, next friday, last friday
Offset	+3d, -1w, +2m, +1y
Clear the field	none

A bare weekday means the next one including today, so friday on a Friday means today. next friday is strictly after today.

--start-time and --end-time are times of day: 09:00, 9am, 21:30, 5:30pm.

none also clears --horizon, --color, --bucket, --parent, and --assignee.

Filtering by completion

timestripe goals list --open      # not done
timestripe goals list --done      # done

--checked still works, but needs an =: --checked=false. The bare --checked false is rejected rather than silently parsed as --checked=true.

Shell completion

timestripe completion zsh > "${fpath[1]}/_timestripe"

Enum flags (--horizon, --color, --sort, --layout, --type) complete their valid values. Invalid values are caught locally, before any network request, with a "did you mean" suggestion.

Output formats

Pick a format with one of these mutually-exclusive flags:

Flag	Output
--json	JSON
--yaml	YAML
--table	Pretty table (default on a TTY)
--markdown	Markdown table
--csv	CSV

When stdout isn't a TTY, the default switches to JSON, so piping is safe:

timestripe goals list --json | jq '.items[] | select(.checked == false) | .name'

# or let the server do the filtering
timestripe goals list --open --json | jq '.items[].name'

Pagination

List commands accept:

Flag	Effect
--limit <n>	Max items returned across all pages
--offset <n>	Starting offset into the result set
--all	Fetch every page; ignores --limit

Configuration

Config and credentials live in $XDG_CONFIG_HOME/timestripe/ (default ~/.config/timestripe/).

Environment overrides:

Variable	Effect
TIMESTRIPE_TOKEN	Bearer token used for all requests; overrides stored credentials.
TIMESTRIPE_BACKEND	Timestripe site root (default https://timestripe.com). Useful for staging or self-hosted environments.
XDG_CONFIG_HOME	Override the config directory base.

Inspect what the CLI sees:

timestripe config show

License

MIT — see LICENSE.

Links

• Timestripe
• Issues
• Releases