eightctl

https://github.com/steipete/eightctl
Admin
A modern Go CLI for Eight Sleep Pods that controls power, temperature, alarms, schedules, audio, and...
Tokens:16,648
Snippets:157
Trust Score:10
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Installation and Configuration

Source: https://context7.com/steipete/eightctl/llms.txt

Instructions on how to install eightctl and set up configuration using a YAML file or environment variables.

```APIDOC
## Installation
```bash
GO111MODULE=on go install github.com/steipete/eightctl/cmd/eightctl@latest
```

## Configuration via YAML
Create a config file at `~/.config/eightctl/config.yaml` with appropriate permissions (0600).

```yaml
email: "you@example.com"
password: "your-password"
# user_id: "abc123"         # auto-resolved via /users/me if omitted
# timezone: "America/New_York"  # defaults to local system timezone
# output: "table"           # table | json | csv
# verbose: false
```

## Configuration via Environment Variables
Alternatively, use environment variables.

```bash
export EIGHTCTL_EMAIL="you@example.com"
export EIGHTCTL_PASSWORD="your-password"
export EIGHTCTL_TIMEZONE="America/New_York"
```

## Verification
Verify authentication by running the `whoami` command.

```bash
eightctl whoami
```

### Example Output
```
userId    email
abc123    you@example.com
```
```

--------------------------------

### Install and Configure eightctl

Source: https://context7.com/steipete/eightctl/llms.txt

Instructions for installing eightctl using Go and configuring it with a YAML file or environment variables. Includes a verification step using the 'whoami' command.

```bash
# Install
GO111MODULE=on go install github.com/steipete/eightctl/cmd/eightctl@latest

# Create config file (permissions must be 0600)
mkdir -p ~/.config/eightctl
cat > ~/.config/eightctl/config.yaml <<'EOF'
email: "you@example.com"
password: "your-password"
# user_id: "abc123"         # auto-resolved via /users/me if omitted
# timezone: "America/New_York"  # defaults to local system timezone
# output: "table"           # table | json | csv
# verbose: false
EOF
chmod 600 ~/.config/eightctl/config.yaml

# Or use environment variables (no config file needed)
export EIGHTCTL_EMAIL="you@example.com"
export EIGHTCTL_PASSWORD="your-password"
export EIGHTCTL_TIMEZONE="America/New_York"

# Verify auth works
eightctl whoami
# Output:
# userId    email
# abc123    you@example.com
```

--------------------------------

### Install and Configure eightctl

Source: https://github.com/steipete/eightctl/blob/main/README.md

Build and install the eightctl CLI. Optionally, create a configuration file with your email and password. Ensure the config file has restricted permissions.

```bash
# build + install
GO111MODULE=on go install github.com/steipete/eightctl/cmd/eightctl@latest

# create config (optional; flags/env also work)
mkdir -p ~/.config/eightctl
cat > ~/.config/eightctl/config.yaml <<'CFG'
email: "you@example.com"
password: "your-password"
# user_id: "optional"               # auto-resolved via /users/me
# timezone: "America/New_York"      # defaults to local
# client_id / client_secret optional # defaults to app creds
CFG
chmod 600 ~/.config/eightctl/config.yaml
```

--------------------------------

### Systemd Unit Example for Daemon

Source: https://context7.com/steipete/eightctl/llms.txt

Example configuration for a systemd user service to manage the eightctl daemon. Save this to ~/.config/systemd/user/eightctl.service.

```bash
[Unit]
Description=eightctl daemon
[Service]
ExecStart=/usr/local/bin/eightctl daemon --quiet
Restart=on-failure
[Install]
WantedBy=default.target
```

--------------------------------

### Print Eightctl Version

Source: https://context7.com/steipete/eightctl/llms.txt

Display the installed version of the eightctl CLI.

```bash
eightctl version
```

--------------------------------

### eightctl Command Examples

Source: https://github.com/steipete/eightctl/blob/main/README.md

Examples of using eightctl for various functions including power, temperature, alarms, schedules, audio, base, device information, sleep metrics, autopilot, travel, and household management.

```bash
# status
eightctl status

# Power & temp:
eightctl on
eightctl off
eightctl temp 20

# Away mode:
eightctl away on
eightctl away off

# Schedules & daemon:
eightctl schedule list

# Alarms:
eightctl alarm list
eightctl alarm create --time 07:00 --days Mon,Tue,Wed
eightctl alarm update --id <alarm-id> --time 07:30
eightctl alarm delete --id <alarm-id>
eightctl alarm snooze
eightctl alarm dismiss-all
eightctl alarm vibration-test

# Temperature modes:
eightctl tempmode nap on
eightctl tempmode nap off
eightctl tempmode nap extend
eightctl tempmode nap status
eightctl tempmode hotflash on
eightctl tempmode hotflash off
eightctl tempmode hotflash status
eightctl tempmode events

# Audio:
eightctl audio tracks
eightctl audio categories
eightctl audio state
eightctl audio play
eightctl audio pause
eightctl audio seek --position 120
eightctl audio volume 50
eightctl audio pair
eightctl audio next
eightctl audio favorites list
eightctl audio favorites add --track-id <track-id>
eightctl audio favorites remove --track-id <track-id>

# Base:
eightctl base info
eightctl base angle 10
eightctl base presets
eightctl base preset-run --name "Morning Wake Up"
eightctl base vibration-test

# Device:
eightctl device info
eightctl device peripherals
eightctl device owner
eightctl device warranty
eightctl device online
eightctl device priming-tasks
eightctl device priming-schedule

# Metrics & insights:
eightctl sleep day
eightctl sleep range --from 2023-01-01 --to 2023-01-31
eightctl presence
eightctl presence --from 2023-01-01 --to 2023-01-31
eightctl metrics trends
eightctl metrics intervals
eightctl metrics insights

# Autopilot:
eightctl autopilot details
eightctl autopilot history
eightctl autopilot recap
eightctl autopilot set-level-suggestions
eightctl autopilot set-snore-mitigation

# Travel:
eightctl travel trips
eightctl travel create-trip --name "Vacation" --start-date 2024-03-10 --end-date 2024-03-17
eightctl travel delete-trip --id <trip-id>
eightctl travel plans
eightctl travel create-plan --trip-id <trip-id> --name "Flight"
eightctl travel update-plan --id <plan-id> --arrival-time "14:00"
eightctl travel tasks
eightctl travel airport-search --iata "JFK"
eightctl travel flight-status --flight-number "AA123"

# Household:
eightctl household summary
eightctl household schedule
eightctl household current-set
eightctl household invitations
eightctl household devices
eightctl household users
eightctl household guests

# Misc:
eightctl tracks
eightctl feats
eightctl whoami
eightctl version
```

--------------------------------

### List Household Devices

Source: https://context7.com/steipete/eightctl/llms.txt

Get a list of devices registered within the household.

```bash
eightctl household devices
```

--------------------------------

### Start Daemon with Custom PID File

Source: https://context7.com/steipete/eightctl/llms.txt

Run the daemon and specify a custom path for the process ID file to prevent double-starts.

```bash
eightctl daemon --pid-file /var/run/eightctl.pid
```

--------------------------------

### Start Daemon with Custom Timezone

Source: https://context7.com/steipete/eightctl/llms.txt

Initiate the daemon process using a specified timezone.

```bash
eightctl daemon --timezone "America/Los_Angeles"
```

--------------------------------

### Start Daemon

Source: https://context7.com/steipete/eightctl/llms.txt

Run the persistent daemon that executes scheduled pod actions. The daemon runs until interrupted by SIGINT or SIGTERM.

```bash
eightctl daemon
```

--------------------------------

### View Base Information

Source: https://context7.com/steipete/eightctl/llms.txt

Get detailed information about the adjustable base. Use --output json for structured data.

```bash
eightctl base info --output json
```

--------------------------------

### eightctl Global Flags Examples

Source: https://context7.com/steipete/eightctl/llms.txt

Demonstrates the usage of global flags for controlling logging verbosity, output format, field selection, configuration file path, and inline credential overrides.

```bash
# Verbose debug logging
eightctl --verbose status

# Suppress the "Using config file: ..." banner
eightctl --quiet status

# Override output format inline
eightctl status --output json

# Select specific columns
eightctl status --fields mode,level

# Use a non-default config file
eightctl --config /etc/eightctl/prod.yaml status

# Override credentials inline (useful in CI)
eightctl --email ci@example.com --password "$SECRET" status

# Target a specific pod side for split-bed households
eightctl on --side left
eightctl off --side right
eightctl temp 20 --side left

# Target a specific user ID directly
eightctl on --target-user-id "user-abc123"
```

--------------------------------

### View Device Information

Source: https://context7.com/steipete/eightctl/llms.txt

Get detailed information about your Eight Sleep device. Use --output json for structured data.

```bash
eightctl device info --output json
```

--------------------------------

### Dry-run Daemon Schedule

Source: https://context7.com/steipete/eightctl/llms.txt

Verify the configured schedule without executing any actions. This is useful for testing your schedule setup.

```bash
eightctl daemon --dry-run
```

--------------------------------

### Get Eight Sleep Pod Status

Source: https://context7.com/steipete/eightctl/llms.txt

Shows the current pod mode and temperature level. Automatically discovers and displays status for all sides in split-bed setups.

```bash
# Show status (auto-discovers household sides)
eightctl status
# side    name       user_id      mode    level
```

--------------------------------

### View Autopilot Recap

Source: https://context7.com/steipete/eightctl/llms.txt

Get a summary of the previous night's Autopilot performance.

```bash
eightctl autopilot recap
```

--------------------------------

### `status` - Pod Status

Source: https://context7.com/steipete/eightctl/llms.txt

Shows current pod mode and temperature level. Automatically discovers household sides for split-bed setups.

```APIDOC
## `status` — Pod Status

Shows current pod mode and temperature level. Automatically discovers household sides for split-bed setups.

### Usage

```bash
eightctl status
```

### Example Output

```
side    name       user_id      mode    level
```
```

--------------------------------

### Manage Audio Playback

Source: https://context7.com/steipete/eightctl/llms.txt

Controls pod audio, including tracks, categories, playback state, and volume. Supports pairing devices, managing favorites, and getting track recommendations.

```bash
# List available audio tracks
eightctl audio tracks
```

```bash
# List audio categories
eightctl audio categories
```

```bash
# Check current player state
eightctl audio state
```

```bash
# Play a specific track
eightctl audio play --track "track-001"
```

```bash
# Pause playback
eightctl audio pause
```

```bash
# Seek to a position (milliseconds)
eightctl audio seek --position 30000
```

```bash
# Set volume (0-100)
eightctl audio volume --level 70
```

```bash
# Pair audio device
eightctl audio pair
```

```bash
# Get recommended next track
eightctl audio next
```

```bash
# List favorite tracks
eightctl audio favorites list
```

```bash
# Add a track to favorites
eightctl audio favorites add --track "track-001"
```

```bash
# Remove a track from favorites
eightctl audio favorites remove --track "track-001"
```

--------------------------------

### Create a Travel Trip

Source: https://context7.com/steipete/eightctl/llms.txt

Add a new travel trip to manage jet-lag adjustments. Requires destination, start date, end date, and trip timezone.

```bash
eightctl travel create-trip \
  --destination "Tokyo" \
  --start-date "2025-03-01" \
  --end-date "2025-03-10" \
  --trip-timezone "Asia/Tokyo"
```

--------------------------------

### Get Current Base Angle

Source: https://context7.com/steipete/eightctl/llms.txt

Retrieve the current angle setting of the adjustable base.

```bash
eightctl base angle
```

--------------------------------

### Get Sleep Metrics and Insights

Source: https://context7.com/steipete/eightctl/llms.txt

Retrieves aggregated sleep trends, raw session intervals, and AI insights for a specified date range. Supports JSON output for trends.

```bash
# Fetch sleep trends for a date range
eightctl metrics trends --from "2025-01-01" --to "2025-01-07"
```

```bash
# Fetch trends as JSON
eightctl metrics trends --from "2025-01-01" --to "2025-01-07" --output json
```

```bash
# Fetch raw session intervals by session ID
eightctl metrics intervals --id "session-abc123"
```

```bash
# Fetch AI-powered sleep insights
eightctl metrics insights
```

--------------------------------

### Adjustable Base Controls

Source: https://context7.com/steipete/eightctl/llms.txt

Controls the Eight Sleep adjustable base, including viewing info, getting the current angle, listing presets, running a preset, and performing a vibration test.

```APIDOC
## `base` — Adjustable Base Controls

Controls the Eight Sleep adjustable base: info, angle, presets, run a preset, and vibration test.

```bash
# View base info
eightctl base info --output json

# Get current base angle
eightctl base angle

# List available presets
eightctl base presets

# Run a preset by name/ID
eightctl base preset-run

# Run a vibration test on the base
eightctl base vibration-test
```
```

--------------------------------

### List Available Base Presets

Source: https://context7.com/steipete/eightctl/llms.txt

Show all the pre-configured presets available for the adjustable base.

```bash
eightctl base presets
```

--------------------------------

### View Warranty Details

Source: https://context7.com/steipete/eightctl/llms.txt

Retrieve information regarding the device's warranty status and expiration.

```bash
eightctl device warranty
```

--------------------------------

### Create a Travel Plan

Source: https://context7.com/steipete/eightctl/llms.txt

Add a new plan within a specific trip, including a name and date.

```bash
eightctl travel create-plan --trip "trip-abc123" --name "Day 1 arrival" --date "2025-03-01"
```

--------------------------------

### View Tasks for a Plan

Source: https://context7.com/steipete/eightctl/llms.txt

List all tasks associated with a specific travel plan.

```bash
eightctl travel tasks --plan "plan-xyz"
```

--------------------------------

### List Device Peripherals

Source: https://context7.com/steipete/eightctl/llms.txt

Display information about connected device peripherals, such as the adjustable base.

```bash
eightctl device peripherals
```

--------------------------------

### View Household Schedule

Source: https://context7.com/steipete/eightctl/llms.txt

Display the current temperature schedule for the household.

```bash
eightctl household schedule
```

--------------------------------

### Run Base Preset

Source: https://context7.com/steipete/eightctl/llms.txt

Activate a specific preset on the adjustable base by its name or ID.

```bash
eightctl base preset-run
```

--------------------------------

### Device Information Commands

Source: https://context7.com/steipete/eightctl/llms.txt

Retrieves device info, peripherals, ownership, warranty, online status, priming tasks, and priming schedule.

```APIDOC
## `device` — Device Information

Retrieves device info, peripherals, ownership, warranty, online status, priming tasks, and priming schedule.

```bash
# View device info
eightctl device info --output json

# List device peripherals (e.g., adjustable base)
eightctl device peripherals

# Check device ownership
eightctl device owner

# View warranty details
eightctl device warranty

# Check if device is online
eightctl device online

# View priming tasks
eightctl device priming-tasks

# View priming schedule
eightctl device priming-schedule
```
```

--------------------------------

### Configure Daemon Schedule

Source: https://context7.com/steipete/eightctl/llms.txt

Add a schedule to your configuration file for the persistent daemon. The daemon executes pod actions based on this schedule.

```bash
cat >> ~/.config/eightctl/config.yaml <<'EOF'
schedule:
  - time: "22:00"
    action: "temp"
    temperature: "68F"
  - time: "22:05"
    action: "on"
  - time: "07:00"
    action: "off"
EOF
```

--------------------------------

### View Device Priming Tasks

Source: https://context7.com/steipete/eightctl/llms.txt

List any pending or active priming tasks for the device.

```bash
eightctl device priming-tasks
```

--------------------------------

### Go Tooling for eightctl

Source: https://github.com/steipete/eightctl/blob/main/README.md

Information on the Go version compatibility and build tooling used by eightctl. It targets Go 1.26.2 and integrates with standard Go development tools.

```bash
# Go: module targets Go 1.26.2 and lets `actions/setup-go` read `go.mod`.
# Make: `make fmt` (tracked `go tool` gofumpt), `make lint` (golangci-lint), `make test`, `make coverage`.
# Coverage: CI enforces >=85% on core packages (`internal/client`, `config`, `daemon`, `output`, `tokencache`); command wiring still runs through `go test ./...`.
# CI: `.github/workflows/ci.yml` runs format, lint, tests, and the coverage gate.
# pnpm scripts (optional): `pnpm eightctl|start|build|lint|format|test|coverage` (see package.json).
```

--------------------------------

### Run Scheduled Actions with Daemon Runner

Source: https://context7.com/steipete/eightctl/llms.txt

Executes scheduled 'on', 'off', and 'temp' actions using a slice of ScheduleItem. Requires client initialization, timezone loading, and a context for cancellation. Set DryRun to false to execute real commands.

```go
package main

import (
    "context"
    "fmt"
    "time"
    "log"

    "github.com/steipete/eightctl/internal/client"
    "github.com/steipete/eightctl/internal/daemon"
)

func main() {
    // ParseTemp: convert Fahrenheit, Celsius, or raw level to internal scale
    lvl, err := daemon.ParseTemp("68F")   // → -4
    fmt.Println(lvl, err)
    lvl, _ = daemon.ParseTemp("20C")      // → -4
    lvl, _ = daemon.ParseTemp("50")       // → 50 (raw level)
    lvl, _ = daemon.ParseTemp("-40")      // → -40

    // Build a schedule
    items := []daemon.ScheduleItem{
        {Time: "22:00", Action: "temp", Temperature: "68F"},
        {Time: "22:05", Action: "on"},
        {Time: "07:00", Action: "off"},
    }

    cl := client.New("you@example.com", "password", "", "", "")

    loc, err := time.LoadLocation("America/New_York")
    if err != nil {
        log.Fatal(err)
    }

    runner := daemon.Runner{
        Items:    items,
        Client:   cl,
        Timezone: loc,
        DryRun:   true,  // set false to execute real commands
        PIDFile:  "/tmp/eightctl-test.pid",
    }

    // Run until SIGINT/SIGTERM or context cancel
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    defer cancel()

    if err := runner.Run(ctx); err != nil {
        log.Fatal("daemon:", err)
    }
    // DRY-RUN 2025-01-15T22:00:00-05:00 temp 68F
    // DRY-RUN 2025-01-15T22:05:00-05:00 on
    // DRY-RUN 2025-01-15T07:00:00-05:00 off
}
```

--------------------------------

### View Device Priming Schedule

Source: https://context7.com/steipete/eightctl/llms.txt

Display the scheduled priming tasks for the device.

```bash
eightctl device priming-schedule
```

--------------------------------

### Check Device Ownership

Source: https://context7.com/steipete/eightctl/llms.txt

Verify the ownership details of the Eight Sleep device.

```bash
eightctl device owner
```

--------------------------------

### Save and Load OAuth Tokens

Source: https://context7.com/steipete/eightctl/llms.txt

Stores OAuth tokens in the OS keyring (with file fallback) namespaced by identity. Clears cached tokens on logout.

```go
package main

import (
    "time"
    "github.com/steipete/eightctl/internal/tokencache"
)

id := tokencache.Identity{
    BaseURL:  "https://client-api.8slp.net/v1",
    ClientID: "0894c7f33bb94800a03f1f4df13a4f38",
    Email:    "you@example.com",
}

// Save a token after successful OAuth
expiry := time.Now().Add(3600 * time.Second)
if err := tokencache.Save(id, "bearer-token-xyz", expiry, "user-abc123"); err != nil {
    // Falls back to file keyring automatically
    panic(err)
}

// Load a cached token (returns error if expired or not found)
cached, err := tokencache.Load(id)
if err == nil {
    fmt.Println("token:", cached.Token)
    fmt.Println("user_id:", cached.UserID)
    fmt.Println("expires:", cached.ExpiresAt)
}

// Clear cached token on logout
_ = tokencache.Clear(id)
```

--------------------------------

### Household Management Commands

Source: https://context7.com/steipete/eightctl/llms.txt

Queries household-level information including summary, schedule, current settings, invitations, devices, users, and guests.

```APIDOC
## `household` — Household Management

Queries household-level information: summary, schedule, current settings, invitations, devices, users, and guests.

```bash
# View household summary
eightctl household summary --output json

# View household schedule
eightctl household schedule

# View current household temperature set
eightctl household current-set

# List household members
eightctl household users

# List household devices
eightctl household devices

# View pending invitations
eightctl household invitations

# View guests
eightctl household guests
```
```

--------------------------------

### List Plans for a Trip

Source: https://context7.com/steipete/eightctl/llms.txt

View all travel plans associated with a specific trip.

```bash
eightctl travel plans --trip "trip-abc123"
```

--------------------------------

### Token Cache (`tokencache` package)

Source: https://context7.com/steipete/eightctl/llms.txt

The `tokencache` package provides functionality to securely store and retrieve OAuth tokens using the OS keyring or a file-based fallback. Tokens are namespaced by base URL, client ID, and email to prevent reuse across different contexts.

```APIDOC
## Token Cache (`tokencache` package)

The token cache stores OAuth tokens in the OS keyring (with a file-based fallback) namespaced by base URL, client ID, and email to prevent cross-account token reuse.

```go
package main

import (
    "time"
    "github.com/steipete/eightctl/internal/tokencache"
)

id := tokencache.Identity{
    BaseURL:  "https://client-api.8slp.net/v1",
    ClientID: "0894c7f33bb94800a03f1f4df13a4f38",
    Email:    "you@example.com",
}

// Save a token after successful OAuth
expiry := time.Now().Add(3600 * time.Second)
if err := tokencache.Save(id, "bearer-token-xyz", expiry, "user-abc123"); err != nil {
    // Falls back to file keyring automatically
    panic(err)
}

// Load a cached token (returns error if expired or not found)
cached, err := tokencache.Load(id)
if err == nil {
    fmt.Println("token:", cached.Token)
    fmt.Println("user_id:", cached.UserID)
    fmt.Println("expires:", cached.ExpiresAt)
}

// Clear cached token on logout
_ = tokencache.Clear(id)
```
```

--------------------------------

### View Autopilot Details

Source: https://context7.com/steipete/eightctl/llms.txt

Retrieve current Autopilot configuration and status. Use --output json for machine-readable output.

```bash
eightctl autopilot details --output json
```

--------------------------------

### Go Client API (`client` package)

Source: https://context7.com/steipete/eightctl/llms.txt

The `client.Client` struct provides a high-level interface for interacting with the Eight Sleep cloud API. It manages authentication, token refresh, retries, and automatic resolution of user and device IDs.

```APIDOC
## Go Client API (`client` package)

The `client.Client` struct wraps all Eight Sleep cloud API calls. It handles OAuth token acquisition and refresh, retry on 429/401, and UserID/DeviceID auto-resolution.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/steipete/eightctl/internal/client"
)

func main() {
    ctx := context.Background()

    // Create a client (uses bundled default OAuth app creds if clientID/Secret are empty)
    cl := client.New("you@example.com", "your-password", "", "", "")

    // Authenticate (fetches and caches token)
    if err := cl.Authenticate(ctx); err != nil {
        log.Fatal("auth failed:", err)
    }

    // Auto-resolve user ID from /users/me
    if err := cl.EnsureUserID(ctx); err != nil {
        log.Fatal("resolve user:", err)
    }
    fmt.Println("userID:", cl.UserID)

    // Turn pod on
    if err := cl.TurnOn(ctx); err != nil {
        log.Fatal(err)
    }

    // Set temperature level (−100..100)
    if err := cl.SetTemperature(ctx, 20); err != nil {
        log.Fatal(err)
    }

    // Set temperature for a specific household user
    if err := cl.SetTemperatureForUser(ctx, "uid-xyz", -40); err != nil {
        log.Fatal(err)
    }

    // Get pod status
    st, err := cl.GetStatus(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("mode=%s level=%d\n", st.CurrentState.Type, st.CurrentLevel)
    // mode=smart level=20

    // Set away mode on
    if err := cl.SetAwayMode(ctx, "", true); err != nil {
        log.Fatal(err)
    }

    // Fetch sleep data for a specific date
    day, err := cl.GetSleepDay(ctx, "2025-01-10", "America/New_York")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("sleep score=%.1f duration=%.0fs\n", day.Score, day.Duration)
    // sleep score=85.2 duration=27540s

    // List audio tracks
    tracks, err := cl.ListTracks(ctx)
    if err != nil {
        log.Fatal(err)
    }
    for _, t := range tracks {
        fmt.Printf("track %s: %s (%s)\n", t.ID, t.Title, t.Type)
    }
}
```
```

--------------------------------

### Fetch Presence Detection Data

Source: https://context7.com/steipete/eightctl/llms.txt

Shows pod-side presence data (occupancy) across a time range. Supports fetching data for a specific range or for the current day.

```bash
# Fetch presence data for the last 7 days
eightctl presence --from "2025-01-01" --to "2025-01-07" --output json
```

```bash
# Fetch presence for today
eightctl presence
```

--------------------------------

### List Smart Schedule

Source: https://context7.com/steipete/eightctl/llms.txt

Display the current Autopilot smart temperature schedule. This command retrieves data from the temperature endpoint.

```bash
eightctl schedule list --output json
```

--------------------------------

### View Household Summary

Source: https://context7.com/steipete/eightctl/llms.txt

Retrieve a summary of household-level information, including schedules and current settings. Use --output json for structured data.

```bash
eightctl household summary --output json
```

--------------------------------

### Run Base Vibration Test

Source: https://context7.com/steipete/eightctl/llms.txt

Initiate a vibration test on the adjustable base for diagnostic purposes.

```bash
eightctl base vibration-test
```

--------------------------------

### View Current Household Temperature Set

Source: https://context7.com/steipete/eightctl/llms.txt

Check the currently set temperature for the household.

```bash
eightctl household current-set
```

--------------------------------

### Version and Identity

Source: https://context7.com/steipete/eightctl/llms.txt

Commands to display the eightctl version and the currently authenticated user's information.

```APIDOC
## `version` and `whoami` — Version and Identity

```bash
# Print eightctl version
eightctl version
# eightctl 0.1.0

# Print authenticated user info
eightctl whoami --output json
# [{"email":"you@example.com","userId":"abc123"}]
```
```

--------------------------------

### Print Authenticated User Info

Source: https://context7.com/steipete/eightctl/llms.txt

Show information about the currently authenticated user, including email and user ID. Use --output json for structured data.

```bash
eightctl whoami --output json
```

--------------------------------

### `on` - Turn Pod On

Source: https://context7.com/steipete/eightctl/llms.txt

Powers the Eight Sleep Pod on, setting the heating/cooling state to 'smart'. Supports targeting specific sides or users.

```APIDOC
## `on` — Turn Pod On

Powers the Eight Sleep Pod on (sets heating/cooling state to "smart").

### Usage

```bash
# Turn on pod for the authenticated user
eightctl on
```

### Options

- `--side <left|right>`: Turn on only the left or right side of a split household.
- `--target-user-id <user_id>`: Turn on the pod for a specific user by their ID.

### Examples

```bash
# Turn on pod for the authenticated user
eightctl on
# Expected Output: pod turned on

# Turn on only the left side of a split household
eightctl on --side left
# Expected Output: pod turned on (left)

# Turn on a specific user by ID
eightctl on --target-user-id "user-abc123"
# Expected Output: pod turned on (user-abc123)
```
```

--------------------------------

### Schedule List

Source: https://context7.com/steipete/eightctl/llms.txt

Lists the smart (Autopilot) temperature schedule. This command surfaces the Autopilot schedule from the temperature endpoint.

```APIDOC
## `schedule` — Autopilot Smart Schedule

Lists the smart (Autopilot) temperature schedule. Note: the older temperature-schedule CRUD API was removed by Eight Sleep; `schedule list` now surfaces the Autopilot schedule from the temperature endpoint.

```bash
# List the current smart schedule
eightctl schedule list --output json
```
```

--------------------------------

### Configure Autopilot Level Suggestions

Source: https://context7.com/steipete/eightctl/llms.txt

Enable or disable Autopilot's level suggestion feature.

```bash
eightctl autopilot level-suggestions --enabled=true
```

--------------------------------

### Format and Filter Output Data

Source: https://context7.com/steipete/eightctl/llms.txt

Renders lists of row maps to stdout in various formats (Table, JSON, CSV). Use FilterFields to trim columns before rendering.

```go
package main

import (
    "github.com/steipete/eightctl/internal/output"
)

rows := []map[string]any{
    {"side": "left",  "mode": "smart", "level": 20},
    {"side": "right", "mode": "off",   "level": 0},
}

// Table output (default)
_ = output.Print(output.FormatTable, []string{"side", "mode", "level"}, rows)
// side    mode    level
// left    smart   20
// right   off     0

// JSON output
_ = output.Print(output.FormatJSON, []string{"side", "mode", "level"}, rows)
// [
//   {"level": 20, "mode": "smart", "side": "left"},
//   {"level": 0,  "mode": "off",   "side": "right"}
// ]

// CSV output
_ = output.Print(output.FormatCSV, []string{"side", "mode", "level"}, rows)
// side,mode,level
// left,smart,20
// right,off,0

// Filter to selected columns only
filtered := output.FilterFields(rows, []string{"side", "level"})
_ = output.Print(output.FormatTable, []string{"side", "level"}, filtered)
// side    level
// left    20
// right   0
```

--------------------------------

### View Pending Invitations

Source: https://context7.com/steipete/eightctl/llms.txt

Check for any outstanding invitations to join the household.

```bash
eightctl household invitations
```

--------------------------------

### Manage Alarms

Source: https://context7.com/steipete/eightctl/llms.txt

Provides full CRUD operations for pod alarms, including snooze, dismiss, and vibration tests. Alarms can be created with specific times, days, and sound/vibration settings.

```bash
# List all alarms
eightctl alarm list
```

```bash
# Create a new alarm (Mon–Fri at 07:00 with vibration)
eightctl alarm create --time "07:00" --days "1,2,3,4,5"
```

```bash
# Create a disabled alarm with sound
eightctl alarm create --time "08:00" --days "0,6" --disabled --sound "soundpack-001"
```

```bash
# Update an alarm's time
eightctl alarm update alarm-001 --time "06:30"
```

```bash
# Enable/disable an alarm
eightctl alarm update alarm-001 --enabled=false
```

```bash
# Delete an alarm
eightctl alarm delete alarm-001
```

```bash
# Snooze a ringing alarm
eightctl alarm snooze alarm-002
```

```bash
# Dismiss a specific alarm
eightctl alarm dismiss alarm-002
```

```bash
# Dismiss all active alarms
eightctl alarm dismiss-all
```

```bash
# Run a vibration test
eightctl alarm vibration-test
```

--------------------------------

### List Household Members

Source: https://context7.com/steipete/eightctl/llms.txt

View a list of users associated with the household.

```bash
eightctl household users
```

--------------------------------

### Show device status

Source: https://context7.com/steipete/eightctl/llms.txt

Displays the current status of connected devices. Use --output json for machine-readable output or --fields to select specific columns.

```bash
eightctl status --output json
```

```bash
eightctl status --all-sides
```

```bash
eightctl status --fields mode,level
```

--------------------------------

### Output Formatting (`output` package)

Source: https://context7.com/steipete/eightctl/llms.txt

The `output.Print` function renders lists of row maps to stdout in various formats (Table, JSON, CSV). `output.FilterFields` can be used to select specific columns before rendering.

```APIDOC
## Output Formatting (`output` package)

The `output.Print` function renders any list of row maps to stdout in the requested format. `output.FilterFields` trims columns before rendering.

```go
package main

import (
    "github.com/steipete/eightctl/internal/output"
)

rows := []map[string]any{
    {"side": "left",  "mode": "smart", "level": 20},
    {"side": "right", "mode": "off",   "level": 0},
}

// Table output (default)
_ = output.Print(output.FormatTable, []string{"side", "mode", "level"}, rows)
// side    mode    level
// left    smart   20
// right   off     0

// JSON output
_ = output.Print(output.FormatJSON, []string{"side", "mode", "level"}, rows)
// [
//   {"level": 20, "mode": "smart", "side": "left"},
//   {"level": 0,  "mode": "off",   "side": "right"}
// ]

// CSV output
_ = output.Print(output.FormatCSV, []string{"side", "mode", "level"}, rows)
// side,mode,level
// left,smart,20
// right,off,0

// Filter to selected columns only
filtered := output.FilterFields(rows, []string{"side", "level"})
_ = output.Print(output.FormatTable, []string{"side", "level"}, filtered)
// side    level
// left    20
// right   0
```
```

--------------------------------

### eightctl Configuration Priority

Source: https://github.com/steipete/eightctl/blob/main/README.md

Understand the order of precedence for eightctl configuration: flags override environment variables, which override the config file. Key fields include email, password, user_id, client_id, client_secret, timezone, output, fields, and verbose.

```bash
# Priority: flags > env vars (`EIGHTCTL_*`) > config file.
# Key fields: `email`, `password`, optional `user_id`, `client_id`, `client_secret`, `timezone`, `output`, `fields`, `verbose`.
# The client auto-resolves `user_id` and `device_id` after authentication.
# Config file permissions are checked (warn if >0600).
```

--------------------------------

### Turn Eight Sleep Pod On

Source: https://context7.com/steipete/eightctl/llms.txt

Powers the Eight Sleep Pod on, setting the heating/cooling state to 'smart'. Supports targeting specific sides of a split-bed or specific user IDs.

```bash
# Turn on pod for the authenticated user
eightctl on
# pod turned on

# Turn on only the left side of a split household
eightctl on --side left
# pod turned on (left)

# Turn on a specific user by ID
eightctl on --target-user-id "user-abc123"
# pod turned on (user-abc123)
```

--------------------------------

### Output Formatting with eightctl

Source: https://github.com/steipete/eightctl/blob/main/README.md

Control the output format of eightctl commands using flags like --output and --fields. Available formats include table, json, and csv.

```bash
# Use --output table|json|csv and --fields field1,field2 to shape output.
# --verbose enables debug logs; --quiet hides the config banner.
eightctl status --output json --fields "id,name,state"
```

--------------------------------

### Run eightctl Daemon

Source: https://github.com/steipete/eightctl/blob/main/README.md

Run the eightctl daemon to manage scheduled routines. Use --dry-run to test the schedule without applying changes.

```bash
# run daemon with your YAML schedule (see docs/example-schedule.yaml)
eightctl daemon --dry-run
```

--------------------------------

### Log Out and Clear Credentials

Source: https://context7.com/steipete/eightctl/llms.txt

Remove the currently cached OAuth token from the OS keyring, effectively logging out the current identity.

```bash
eightctl logout
```

--------------------------------

### View Household Guests

Source: https://context7.com/steipete/eightctl/llms.txt

List any guests currently associated with the household.

```bash
eightctl household guests
```

--------------------------------

### Daemon Scheduled Automation

Source: https://context7.com/steipete/eightctl/llms.txt

Runs a persistent daemon that executes pod actions (on/off/temp) from a YAML schedule at specified times every day. Includes PID-file guarding to prevent double-starts and exits cleanly on SIGINT/SIGTERM.

```APIDOC
## `daemon` — Scheduled Automation

Runs a persistent daemon that executes pod actions (on/off/temp) from a YAML schedule at specified times every day. Includes PID-file guarding to prevent double-starts and exits cleanly on SIGINT/SIGTERM.

```bash
# Add a schedule section to your config.yaml:
cat >> ~/.config/eightctl/config.yaml <<'EOF'
schedule:
  - time: "22:00"
    action: "temp"
    temperature: "68F"
  - time: "22:05"
    action: "on"
  - time: "07:00"
    action: "off"
EOF

# Dry-run to verify schedule without executing
eightctl daemon --dry-run
# daemon started with 3 items
# DRY-RUN 2025-01-15T22:00:00-05:00 temp 68F
# DRY-RUN 2025-01-15T22:05:00-05:00 on
# DRY-RUN 2025-01-15T07:00:00-05:00 off

# Start the daemon (runs until SIGINT/SIGTERM)
eightctl daemon

# Start with a custom timezone
eightctl daemon --timezone "America/Los_Angeles"

# Start with a custom PID file
eightctl daemon --pid-file /var/run/eightctl.pid

# Systemd unit example (save to ~/.config/systemd/user/eightctl.service):
# [Unit]
# Description=eightctl daemon
# [Service]
# ExecStart=/usr/local/bin/eightctl daemon --quiet
# Restart=on-failure
# [Install]
# WantedBy=default.target
```
```

--------------------------------

### Presence Detection

Source: https://context7.com/steipete/eightctl/llms.txt

Shows pod-side presence data (whether each side of the bed is occupied) across a time range.

```APIDOC
## `presence` — Presence Detection

Shows pod-side presence data (whether each side of the bed is occupied) across a time range.

### Presence Data
```bash
# Fetch presence data for the last 7 days
eightctl presence --from "2025-01-01" --to "2025-01-07" --output json

# Fetch presence for today
eightctl presence
```
```

--------------------------------

### Check Pod Status with eightctl

Source: https://github.com/steipete/eightctl/blob/main/README.md

Check the current state of your Eight Sleep Pod. You can provide credentials via environment variables or rely on the configuration file.

```bash
# check pod state
EIGHTCTL_EMAIL=you@example.com EIGHTCTL_PASSWORD=your-password eightctl status
```

--------------------------------

### Alarm Management

Source: https://context7.com/steipete/eightctl/llms.txt

Manage pod alarms including creation, updates, deletion, snoozing, dismissing, and vibration tests.

```APIDOC
## `alarm` — Manage Alarms

Full CRUD for pod alarms, plus snooze, dismiss, and vibration test.

### List all alarms
```bash
eightctl alarm list
# id          time   enabled  days      vibration  sound
# alarm-001   07:00  true     [1 2 3]   true       <nil>
```

### Create a new alarm
```bash
# Create a new alarm (Mon–Fri at 07:00 with vibration)
eightctl alarm create --time "07:00" --days "1,2,3,4,5"
# created alarm alarm-002

# Create a disabled alarm with sound
eightctl alarm create --time "08:00" --days "0,6" --disabled --sound "soundpack-001"
# created alarm alarm-003
```

### Update an alarm
```bash
# Update an alarm's time
eightctl alarm update alarm-001 --time "06:30"
# updated

# Enable/disable an alarm
eightctl alarm update alarm-001 --enabled=false
# updated
```

### Delete an alarm
```bash
eightctl alarm delete alarm-001
# deleted
```

### Snooze a ringing alarm
```bash
eightctl alarm snooze alarm-002
```

### Dismiss an alarm
```bash
# Dismiss a specific alarm
eightctl alarm dismiss alarm-002

# Dismiss all active alarms
eightctl alarm dismiss-all
```

### Run a vibration test
```bash
eightctl alarm vibration-test
```
```

--------------------------------

### Audio Controls

Source: https://context7.com/steipete/eightctl/llms.txt

Manages pod audio features including tracks, categories, playback state, volume, pairing, and favorites.

```APIDOC
## `audio` — Audio Controls

Manages pod audio: tracks, categories, playback state, play/pause/seek/volume, pairing, and favorites.

### Tracks and Categories
```bash
# List available audio tracks
eightctl audio tracks
# id              title                  type
# track-001       Ocean Waves            sleep
# track-002       White Noise            sleep

# List audio categories
eightctl audio categories
```

### Playback Control
```bash
# Check current player state
eightctl audio state

# Play a specific track
eightctl audio play --track "track-001"

# Pause playback
eightctl audio pause

# Seek to a position (milliseconds)
eightctl audio seek --position 30000

# Set volume (0-100)
eightctl audio volume --level 70
```

### Pairing and Recommendations
```bash
# Pair audio device
eightctl audio pair

# Get recommended next track
eightctl audio next
```

### Favorites
```bash
# List favorite tracks
eightctl audio favorites list

# Add a track to favorites
eightctl audio favorites add --track "track-001"

# Remove a track from favorites
eightctl audio favorites remove --track "track-001"
```
```

--------------------------------

### List All Trips

Source: https://context7.com/steipete/eightctl/llms.txt

Retrieve a list of all managed travel trips. Use --output json for structured data.

```bash
eightctl travel trips --output json
```

--------------------------------

### Check Device Online Status

Source: https://context7.com/steipete/eightctl/llms.txt

Determine if the Eight Sleep device is currently connected to the network.

```bash
eightctl device online
```

--------------------------------

### View Autopilot History

Source: https://context7.com/steipete/eightctl/llms.txt

Access the adjustment history for Autopilot features.

```bash
eightctl autopilot history
```

--------------------------------

### Eight Sleep Go Client API Usage

Source: https://context7.com/steipete/eightctl/llms.txt

Wraps Eight Sleep cloud API calls, handling OAuth, retries, and UserID/DeviceID resolution. Use New to create a client.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/steipete/eightctl/internal/client"
)

func main() {
    ctx := context.Background()

    // Create a client (uses bundled default OAuth app creds if clientID/Secret are empty)
    cl := client.New("you@example.com", "your-password", "", "", "")

    // Authenticate (fetches and caches token)
    if err := cl.Authenticate(ctx); err != nil {
        log.Fatal("auth failed:", err)
    }

    // Auto-resolve user ID from /users/me
    if err := cl.EnsureUserID(ctx); err != nil {
        log.Fatal("resolve user:", err)
    }
    fmt.Println("userID:", cl.UserID)

    // Turn pod on
    if err := cl.TurnOn(ctx); err != nil {
        log.Fatal(err)
    }

    // Set temperature level (−100..100)
    if err := cl.SetTemperature(ctx, 20); err != nil {
        log.Fatal(err)
    }

    // Set temperature for a specific household user
    if err := cl.SetTemperatureForUser(ctx, "uid-xyz", -40); err != nil {
        log.Fatal(err)
    }

    // Get pod status
    st, err := cl.GetStatus(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("mode=%s level=%d\n", st.CurrentState.Type, st.CurrentLevel)
    // mode=smart level=20

    // Set away mode on
    if err := cl.SetAwayMode(ctx, "", true); err != nil {
        log.Fatal(err)
    }

    // Fetch sleep data for a specific date
    day, err := cl.GetSleepDay(ctx, "2025-01-10", "America/New_York")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("sleep score=%.1f duration=%.0fs\n", day.Score, day.Duration)
    // sleep score=85.2 duration=27540s

    // List audio tracks
    tracks, err := cl.ListTracks(ctx)
    if err != nil {
        log.Fatal(err)
    }
    for _, t := range tracks {
        fmt.Printf("track %s: %s (%s)\n", t.ID, t.Title, t.Type)
    }
}
```

--------------------------------

### Search for Airports

Source: https://context7.com/steipete/eightctl/llms.txt

Find airport information by providing a query, such as an airport code or city name.

```bash
eightctl travel airport-search --query "NRT"
```

--------------------------------

### Targeting Household Sides with eightctl

Source: https://github.com/steipete/eightctl/blob/main/README.md

Specify which side of a split household to target using the --side flag. Options include 'left', 'right', or 'solo'. You can also target a specific user with --target-user-id.

```bash
# status shows discovered household targets by default when available, including `left` / `right` or inferred `solo`.
# on, off, and temp apply to all discovered household targets by default.
# Use `--side left|right|solo` to target one household side.
# Use `--target-user-id <id>` when you want to address a specific discovered user directly.
# For split households, `eightctl status --output json` is the quickest way to inspect available sides and user IDs.
```

--------------------------------

### Autopilot Commands

Source: https://context7.com/steipete/eightctl/llms.txt

Commands to view and manage Autopilot features, including details, history, recap, level suggestions, and snore mitigation.

```APIDOC
## Autopilot Commands

View current Autopilot details:
```bash
eightctl autopilot details --output json
```

View Autopilot adjustment history:
```bash
eightctl autopilot history
```

View last night's Autopilot recap:
```bash
eightctl autopilot recap
```

Enable Autopilot level suggestions:
```bash
eightctl autopilot level-suggestions --enabled=true
```

Disable Autopilot snore mitigation:
```bash
eightctl autopilot snore-mitigation --enabled=false
```
```

--------------------------------

### Update a Travel Plan

Source: https://context7.com/steipete/eightctl/llms.txt

Modify an existing travel plan by its ID, updating its name or other properties.

```bash
eightctl travel update-plan --plan "plan-xyz" --name "Updated plan name"
```
Tokens:
Raw