Command Reference

The meridian CLI is organized into command groups. Run any command with --help for inline documentation.

meridian --help
meridian timer --help
meridian timer start --help

Authentication (meridian auth)

login

Authenticate with an API key.

meridian auth login
meridian auth login --api-key mt_live_your_key_here

Option	Short	Description
--api-key	-k	API key (prompted if omitted)

On success, the CLI saves the key to your system keyring and auto-discovers your user ID if the workspace has a single member.

logout

Clear stored credentials and user ID.

meridian auth logout

status

Display current authentication status: masked API key, user ID, and API URL.

meridian auth status

set-user

Set the default user ID for timer and entry operations.

meridian auth set-user USER_ID

---

Timer (meridian timer)

start

Start a timer.

meridian timer start "Design review"
meridian timer start "API work" --project "Backend" --billable

Option	Short	Description
NAME	—	Description of what you’re working on (positional, optional)
--project	-p	Project name or ID (fuzzy matched)
--client	-c	Client name or ID (fuzzy matched)
--billable	-b	Mark as billable
--notes	-n	Additional notes

Tip

Project and client names are fuzzy matched — you don’t need to type the exact name. For example, --project back will match a project named “Backend API”.

stop

Stop the active timer and save the time entry.

meridian timer stop
meridian timer stop --name "Updated description"

Option	Short	Description
--name	—	Override the description before stopping
--notes	-n	Add notes before stopping

status

Check the current timer state.

meridian timer status

Displays elapsed time, description, start time, and billable flag if a timer is running.

---

Time Entries (meridian entries)

list

List time entries with optional filtering.

meridian entries list
meridian entries list --date today
meridian entries list --date this-week --format json
meridian entries list --start 2026-03-01 --end 2026-03-11

Option	Short	Description
--date	-d	Date preset or YYYY-MM-DD (see presets below)
--start	—	Start date (YYYY-MM-DD)
--end	—	End date (YYYY-MM-DD)
--project	-p	Filter by project ID
--limit	-l	Max entries to return (default: 50)
--format	-f	Output format: table, json, csv

Date presets: today, yesterday, this-week, last-week, this-month

If --start and --end are provided, --date is ignored.

create

Create a completed time entry with explicit start and end times.

meridian entries create "Client meeting" \
  --start 2026-03-11T09:00:00 \
  --end 2026-03-11T10:30:00 \
  --project "Acme" \
  --billable

Option	Short	Description
NAME	—	Description (positional, required)
--start	-s	Start time in ISO 8601 (required)
--end	-e	End time in ISO 8601 (required)
--project	-p	Project name or ID (fuzzy matched)
--client	-c	Client name or ID (fuzzy matched)
--billable	-b	Mark as billable
--notes	-n	Additional notes

edit

Update an existing time entry.

meridian entries edit ENTRY_ID --sort-key SORT_KEY --name "Updated name" --billable

Option	Short	Description
ENTRY_ID	—	Time entry ID (positional, required)
--sort-key	-s	Time entry sort key (required)
--name	—	Update description
--end	-e	Update end time (ISO 8601)
--notes	-n	Update notes
--billable	-b	Set billable flag
--project	-p	Update project (name or ID, fuzzy matched)

Caution

Both ENTRY_ID and --sort-key are required. You can find these values in the output of meridian entries list --format json.

delete

Delete a time entry.

meridian entries delete ENTRY_ID --sort-key SORT_KEY
meridian entries delete ENTRY_ID --sort-key SORT_KEY --force

Option	Short	Description
ENTRY_ID	—	Time entry ID (positional, required)
--sort-key	-s	Time entry sort key (required)
--force	-y	Skip confirmation prompt

---

Projects (meridian projects)

list

List all projects.

meridian projects list
meridian projects list --format csv

Option	Short	Description
--format	-f	Output format: table, json, csv

create

Create a new project.

meridian projects create --name "Website Redesign" --client "Acme" --billable

Option	Short	Description
--name	-n	Project name (required)
--client	-c	Client name or ID (fuzzy matched)
--billable	-b	Default entries to billable
--color	—	Project color (hex code, e.g. #4A90D9)

---

Clients (meridian clients)

list

List all clients.

meridian clients list
meridian clients list --format json

Option	Short	Description
--format	-f	Output format: table, json, csv

create

Create a new client.

meridian clients create "Acme Corp" --email billing@acme.com --contact "Jane Doe"

Option	Short	Description
NAME	—	Client name (positional, required)
--email	-e	Client email address
--contact	-c	Contact person name

---

Configuration (meridian config)

set

Set a configuration value.

meridian config set api_url https://api.meridiantrack.com

get

Get a configuration value.

meridian config get api_url

show

Display all configuration values as JSON.

meridian config show

---

Global Commands

version

Display the CLI version.

meridian version

---

Output Formats

The --format flag is available on entries list, projects list, and clients list. Three formats are supported:

Format	Description
table	Rich-formatted table (default, best for terminals)
json	JSON array (best for scripting and piping)
csv	Comma-separated values (best for spreadsheet import)

Fuzzy Name Matching

When specifying a project or client by name, the CLI uses fuzzy matching with a 70% similarity threshold. This means you can type partial names:

# These all match a project named "Backend API"
meridian timer start --project "Backend API"
meridian timer start --project "backend"
meridian timer start --project "back"

If no match is found above the threshold, the CLI displays available options and exits. To bypass fuzzy matching entirely, pass the resource ID directly.