Floq

日本語

A terminal-based GTD (Getting Things Done) task manager with MS-DOS style themes.

Features

• TUI Interface: Interactive terminal UI built with Ink (React for CLI)
• GTD Workflow: Inbox, Next Actions, Waiting For, Someday/Maybe, Done (shows last 7 days)
• Kanban Mode: 3-column kanban board view (TODO, Doing, Done)
• Projects: Organize tasks into projects with progress tracking
• Contexts: Tag tasks with contexts (@work, @home, etc.) and filter by context. New tasks inherit the active context filter
• Focus Mode: Mark tasks as "today's focus" (★) and filter to show only focused tasks
• Effort Size: Tag tasks with effort size (S/M/L) to pick the right task for your available time
• Task Search: Quick search across all tasks with /
• Comments: Add notes and comments to tasks
• Cloud Sync: Optional sync with Turso using embedded replicas
• Google Calendar: Display today's events via iCal URL or OAuth integration
• Themes: Multiple themes including MS-DOS nostalgic styles and Dragon Quest RPG style
• Splash Screen: Configurable startup splash with Dragon Quest style for retro themes
• i18n: English and Japanese support
• Vim-style Navigation: Use hjkl or arrow keys
• Setup Wizard: First-run wizard for easy configuration

Installation

npm install -g floq

From Source

git clone https://github.com/polidog/gtd-cli.git
cd gtd-cli
npm install
npm run build
npm link

Usage

TUI Mode

floq

Keyboard Shortcuts (GTD Mode)

| Key | Action | |-----|--------| | 1-6 | Switch tabs (Inbox/Next/Waiting/Someday/Projects/Done) | | h/l or ←/→ | Previous/Next tab | | j/k or ↑/↓ | Navigate tasks | | a | Add task | | d | Mark as done | | n | Move to Next Actions | | s | Move to Someday/Maybe | | i | Move to Inbox | | w | Move to Waiting For (prompts for person) | | p | Convert to project | | P | Link to project | | c | Set context | | @ | Filter by context | | g | Toggle focus (★) on selected task | | G | Toggle focus filter (show only focused tasks) | | E | Set effort size (S/M/L) | | Enter | Open task detail / Open project | | Esc/b | Back | | / | Search tasks | | r | Refresh | | u | Undo | | Ctrl+r | Redo | | ? | Help | | q | Quit |

Search

| Key | Action | |-----|--------| | / | Start search mode | | ↑/↓ or Ctrl+j/k | Navigate search results | | Enter | Jump to selected task's tab and select it | | Esc | Cancel search |

Project Detail View

| Key | Action | |-----|--------| | j/k | Navigate tasks | | a | Add task to project | | d | Mark task as done | | Enter | Open task detail | | Esc/b | Back to projects list |

Task Detail View

| Key | Action | |-----|--------| | i | Add comment | | d | Delete selected comment | | P | Link to project | | j/k | Navigate comments | | Esc/b | Back to list / project |

Keyboard Shortcuts (Kanban Mode)

| Key | Action | |-----|--------| | 1-3 | Switch columns (TODO/Doing/Done) | | h/l or ←/→ | Previous/Next column | | j/k or ↑/↓ | Navigate tasks | | a | Add task | | d | Mark as done | | m | Move task right (→) | | Backspace | Move task left (←) | | c | Set context | | @ | Filter by context | | g | Toggle focus (★) on selected task | | G | Toggle focus filter (show only focused tasks) | | E | Set effort size (S/M/L) | | Enter | Open task detail | | / | Search tasks | | r | Refresh | | u | Undo | | Ctrl+r | Redo | | ? | Help | | q | Quit |

Task Detail View (Kanban)

| Key | Action | |-----|--------| | i | Add comment | | d | Delete selected comment | | j/k | Navigate comments | | Esc/b | Back to board |

Setup Wizard

On first run, Floq will launch an interactive setup wizard to configure:

• Language (English/Japanese)
• Theme selection
• View mode (GTD/Kanban)

You can also run the wizard manually:

floq setup

CLI Commands

# Add task
floq add "Task title"
floq add "Task title" -p "Project name"
floq add "Task title" -c work           # With context

# List tasks
floq list              # All non-done tasks
floq list inbox        # Inbox only
floq list next         # Next actions
floq list waiting      # Waiting for
floq list someday      # Someday/maybe
floq list projects     # Projects

# Move task
floq move <id> next
floq move <id> waiting "Person name"
floq move <id> someday

# Complete task
floq done <id>

# Projects
floq project add "Project name"
floq project list
floq project show <id>
floq project complete <id>

# Comments
floq comment <id> "Comment text"  # Add comment
floq comment <id>                 # List comments

# Contexts
floq context list                 # List available contexts
floq context add <name>           # Add new context
floq context remove <name>        # Remove context

Configuration

# Show configuration
floq config show

# Set language
floq config lang en    # English
floq config lang ja    # Japanese

# Set theme (interactive selector with j/k navigation)
floq config theme

# Or specify directly
floq config theme modern           # Default
floq config theme synthwave        # Neon 80s aesthetic

# Set view mode (interactive selector)
floq config mode

# Or specify directly
floq config mode gtd               # GTD workflow (default)
floq config mode kanban            # Kanban board

# Set database path
floq config db /path/to/custom.db
floq config db                     # Reset to default

# Splash screen settings
floq config splash                 # Show current setting
floq config splash 3000            # Set to 3 seconds
floq config splash off             # Disable splash screen
floq config splash key             # Wait for key press

# Reset database (delete all data)
floq db reset                      # With confirmation
floq db reset --force              # Skip confirmation

Cloud Sync (Turso)

Floq supports cloud synchronization using Turso, a SQLite-compatible database service. With embedded replicas, your data syncs to the cloud while remaining available offline.

Setup

1. Create a Turso database at turso.tech
2. Get your database URL and auth token
3. Configure Floq:

# Enable Turso sync
floq config turso --url libsql://your-db.turso.io --token your-auth-token

# Check configuration
floq config show

# Manual sync
floq sync

# Disable Turso sync
floq config turso --disable

How It Works

• Embedded Replicas: Local SQLite database syncs with Turso cloud
• Offline Support: Works offline, syncs when connected
• Auto Sync: Background sync every 60 seconds when online
• Separate Database: Turso mode uses floq-turso.db to avoid conflicts

Status Indicator

• TUI header shows connection status (cloud icon for Turso, local icon for local mode)
• CLI commands display 🔄 Turso sync: hostname when Turso is enabled

Google Calendar Integration

Floq can display your Google Calendar events in the TUI. Two methods are available:

Option 1: iCal URL (Simple, No Authentication)

Use Google Calendar's secret iCal URL for read-only access without OAuth setup.

# Get your iCal URL from Google Calendar:
# Settings > (Your Calendar) > Integrate calendar > "Secret address in iCal format"

floq calendar add "https://calendar.google.com/calendar/ical/..." -n "My Calendar"
floq calendar show

Option 2: Google OAuth (Full API Access)

Use OAuth for better reliability and access to all your calendars.

Setup

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable Google Calendar API:
   • Go to APIs & Services > Library
   • Search for "Google Calendar API"
   • Click Enable
4. Configure OAuth consent screen:
   • Go to APIs & Services > OAuth consent screen
   • Select External and click Create
   • Fill in app name and required fields
   • Add your email to Test users
5. Create OAuth credentials:
   • Go to APIs & Services > Credentials
   • Click Create Credentials > OAuth client ID
   • Application type: TV and Limited Input devices (not "Desktop app")
   • Copy the Client ID and Client Secret

Configuration

# Set OAuth credentials (or use environment variables)
floq calendar config --client-id "your-client-id.apps.googleusercontent.com" --client-secret "your-secret"

# Or use environment variables
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-secret"

# Login with Google
floq calendar login
# → Opens browser for authentication
# → Enter the displayed code when prompted

# Select a calendar
floq calendar select
# → Shows list of your calendars
# → Enter the number to select

# View configuration and today's events
floq calendar show

# Refresh calendar cache
floq calendar sync

# Logout
floq calendar logout

Calendar Commands

# iCal mode
floq calendar add <url> [-n name]   # Add iCal URL
floq calendar remove                 # Remove calendar

# OAuth mode
floq calendar config --client-id <id> --client-secret <secret>
floq calendar login                  # Google OAuth login
floq calendar logout                 # Clear OAuth tokens
floq calendar select                 # Select calendar (interactive)

# Common commands
floq calendar show                   # Show config and today's events
floq calendar sync                   # Refresh cache
floq calendar enable                 # Enable display
floq calendar disable                # Disable display

Themes

26 themes available. Use floq config theme for interactive selection (j/k to navigate).

Some themes feature a Dragon Quest RPG style UI with titled message boxes, 2-column layouts, and retro splash screens. Themes with DQ-style: turbo-pascal, msx, pc-98.

| Theme | Description | |-------|-------------| | modern | Clean, minimal style (default) | | norton-commander | MS-DOS file manager style | | dos-prompt | Green CRT monitor | | turbo-pascal | Borland IDE style | | classic-mac | Macintosh System 7 monochrome | | apple-ii | Apple ][ green phosphor | | commodore-64 | C64 blue/purple palette | | amiga-workbench | Amiga orange & blue | | matrix | Digital rain green | | amber-crt | Amber monitor | | phosphor | CRT phosphor glow | | solarized-dark | Solarized dark palette | | solarized-light | Solarized light palette | | synthwave | Neon 80s aesthetic | | paper | Light minimal theme | | coffee | Warm brown tones | | nord | Arctic, north-bluish palette | | dracula | Dark theme with vibrant colors | | monokai | Classic editor vivid colors | | gruvbox | Retro groove warm tones | | tokyo-night | Tokyo night lights inspired | | catppuccin | Soothing pastel theme | | ocean | Deep sea blue theme | | sakura | Cherry blossom pink | | msx | MSX computer (TMS9918) | | pc-98 | NEC PC-9801 style |

Note: Background colors depend on your terminal settings.

Data Storage

• Config: ~/.config/floq/config.json
• Database: ~/.local/share/floq/floq.db (or floq-turso.db with Turso enabled)

License

MIT