Wrixton Quickstart: Install the CLI and Add Your First Items

The Wrixton CLI is a Python package that communicates with the hosted API at projects.wrixton.xyz. All you need to get started is Python 3.11 or later, a Wrixton account (ask the instance owner for an API key), and a couple of minutes. The five steps below take you from zero to a populated list.

Install the CLI

Clone the repository and run the bundled setup script. init.sh creates a virtual environment, installs the track package into it, and symlinks the binary to ~/.local/bin/track.

git clone https://github.com/rwwarren/project-tracker
cd project-tracker
./init.sh

The script will print something like:

==> creating venv (python3.12)
==> upgrading pip
==> installing track
==> symlinking track → /home/you/.local/bin/track

done. add to your shell config if not already:
  export PATH="$HOME/.local/bin:$PATH"

next: track config   # paste your api_key

Add ~/.local/bin to your PATH if it isn’t already, then open a new shell (or source your profile):

export PATH="$HOME/.local/bin:$PATH"

Configure your API key

Run track config. It will prompt you for your API key with a hidden input (nothing is echoed to the terminal) and write the result to ~/.track/config.toml with permissions 600.

track config

Track api_key: ········
wrote /home/you/.track/config.toml
authenticated as ryan

The app URL defaults to the shared deployment at https://projects.wrixton.xyz, so the API key is the only thing you normally need to enter. If you want to point at a local development server, pass --api-url http://localhost:3000 or set TRACK_API_URL in your environment. You can also supply the key directly with TRACK_API_KEY instead of storing it in the config file.

Verify your setup

Confirm authentication is working and check what’s already on your plate:

track whoami
track today

ryan  (309234af-1a2b-4c3d-8e9f-0a1b2c3d4e5f)

nothing on the radar today. nice.

track whoami prints your username and user ID. track today shows everything due today or overdue, sorted by priority and due date. A clean slate means you’re ready to add items.

Add your first items

Create a one-off todo with a due date, a recurring chore, and a new project with a task inside it:

# A todo due in two days, priority 2, tagged admin
track add todo "Call dentist" --due 2d -p 2 --tags admin

# A chore that recurs every 3 months with a time estimate
track add chore "Replace HVAC filter" --every "3 months" --estimate 20m

# A project and a task that belongs to it
track add project "Kitchen renovation" --slug kitchen-reno
track add task "Pick countertops" --project kitchen-reno --due 2w

Each command prints the newly created item:

  t-1f3a  TODO   P2  Call dentist  #admin  2025-07-14 (2d)
  c-80f8  CHORE  P3  Replace HVAC filter  ~20m
  p-a3c1  kitchen-reno  Kitchen renovation
  k-9d2e  TASK   P3  Pick countertops [kitchen-reno]  2025-07-28 (2w)

IDs use a kind prefix (t- for todos, k- for tasks, c- for chores, p- for projects, s- for shopping and gifts, g- for groceries) followed by a short hex string. You’ll use these IDs for follow-up operations like track done, track snooze, and track edit.

--due accepts YYYY-MM-DD, today, tomorrow, day names (mon–sun), and relative shortcuts like 3d (three days) or 2w (two weeks). The --every flag for recurrence accepts daily, weekly, biweekly, monthly, quarterly, yearly, or an <N> <unit> string like 3 months.

Check your list

Pull up your focus list and your full item list to confirm everything landed correctly:

track today
track ls

focus for 2025-07-12:
  t-1f3a  TODO   P2  Call dentist  #admin  2025-07-14 (2d)
  k-9d2e  TASK   P3  Pick countertops [kitchen-reno]  2025-07-28 (2w)

  t-1f3a  TODO   P2  Call dentist  #admin  2025-07-14 (2d)
  c-80f8  CHORE  P3  Replace HVAC filter  ~20m  (due in 3 months)
  k-9d2e  TASK   P3  Pick countertops [kitchen-reno]  2025-07-28 (2w)

track today blends priority and due date into a single focus list and sums time estimates — ~3h 40m estimated across 5 items — so you can see at a glance whether the day is realistic. track ls shows everything active across all kinds. When you finish an item, mark it done with its ID:

track done t-1f3a

From here you can explore the rest of what Wrixton offers: shopping lists (track add buy), gift tracking (track add gift --for "Sister" --occasion Birthday), grocery runs (track add grocery), and list sharing (track share groceries alice). Run track --help or track <command> --help at any time to see available flags.