sleepycli

A small Go CLI for calculating sleep and wake times around 90-minute sleep cycles.

sleepycli helps you answer questions like:

• “If I sleep now, when should I wake up?”
• “If I want to wake up at 07:00, when should I go to bed?”
• “How many full sleep cycles fit between two times?”

The tool supports four main modes: calculate from now, from a target wake time, from a target sleep time, or across a window of time.

Features

• Interactive TUI mode when run without flags
• Calculate wake times from the current time
• Calculate bedtimes for a target wake time
• Calculate wake times for a target sleep time
• Calculate full sleep cycles within a sleep window
• Configurable fall-asleep buffer
• Configurable minimum and maximum cycle count
• Input validation for modes, time format, and cycle ranges
• Custom help output
• Bash completion script
• Pull request CI for linting and tests

How it works

The calculator uses a 90-minute sleep cycle and adds an optional buffer to represent the time it takes to fall asleep.

Defaults:

• Sleep cycle: 90 minutes
• Buffer: 15 minutes
• Displayed cycles: 4 to 6

Installation

Download binary

Download the latest binary and completion script from the releases page.

Linux / macOS

tar -xzf sleepycli_<version>_<os>_<arch>.tar.gz
chmod +x sleepycli
sudo mv sleepycli /usr/local/bin/sleepycli

To enable bash completion, add this to your ~/.bashrc:

source <(curl -sL https://github.com/TyostoKarry/sleepycli/releases/latest/download/sleepycli-completion.bash)

Windows

Extract the .zip archive and move sleepycli.exe to a folder in your PATH.

go install

If you have Go installed:

go install github.com/TyostoKarry/sleepycli@latest

Build from source

git clone https://github.com/TyostoKarry/sleepycli.git
cd sleepycli
go build -o sleepycli .

Interactive mode

Run sleepycli without any flags to launch the interactive TUI:

sleepycli

• Navigate with ↑ / ↓
• Press enter on a mode to select it and type your time
• Adjust settings (buffer, cycle range) from the settings section
• Press enter to confirm — the result is printed to your terminal
• Press q to quit without output

CLI flags

sleepycli [mode] [options]

Choose exactly one mode.

Modes

--now

Calculate wake times starting from the current time.

sleepycli --now

--wake HH:MM

Calculate suggested bedtimes for a target wake time.

sleepycli --wake 07:00

--sleep HH:MM

Calculate suggested wake times for a target sleep time.

sleepycli --sleep 22:30

--from HH:MM --to HH:MM

Calculate how many complete sleep cycles fit inside a time window.

sleepycli --from 22:00 --to 07:00

Options examples

Use a custom fall-asleep buffer

sleepycli --wake 07:00 --buffer 30

Show a different cycle range

sleepycli --sleep 23:00 --cycles-min 3 --cycles-max 7

Sample output

--wake 07:00

To wake up at 07:00
──────────────────────────────
Assuming 15 min to fall asleep

  6 cycles  →  sleep at 21:45  (9h 00m)
  5 cycles  →  sleep at 23:15  (7h 30m)
  4 cycles  →  sleep at 00:45  (6h 00m)

--from 22:00 --to 07:00

Between 22:00 and 07:00
──────────────────────────────
Assuming 15 min to fall asleep

  5 complete cycles  (7h 30m)
  75 minutes remaining

Flag reference

Flag	Description	Default
-n, --now	Calculate wake times from the current time	-
-w, --wake HH:MM	Calculate bedtimes for a target wake time	-
-s, --sleep HH:MM	Calculate wake times for a target sleep time	-
-f, --from HH:MM	Start of sleep window, used with --to	-
-t, --to HH:MM	End of sleep window, used with --from	-
-b, --buffer int	Minutes needed to fall asleep	15
-m, --cycles-min int	Minimum cycles to show	4
-x, --cycles-max int	Maximum cycles to show	6
-g, --good-night	Print random good night ASCII art	-
-v, --version	Print version	-
-h, --help	Show help	-

Input rules

• Time format is 24-hour HH:MM
• Short hour values like 7:00 are accepted
• Modes cannot be combined
• --from and --to must be used together
• --now, --wake and --sleep are mutually exclusive
• --cycles-min cannot be greater than --cycles-max
• Buffer and cycle values cannot be negative

CI

The repository includes a pull request workflow that:

• runs golangci-lint
• runs go test ./...
• triggers on pull requests targeting main