freelo-cli

Command-line interface for Freelo.io — manage projects, tasklists, tasks, comments, time entries, and files without leaving the terminal.

Status: early access. Authentication, configuration, and an introspectable command surface are shipped. Resource commands (projects, tasklists, tasks, comments, time entries, files) are landing one spec at a time.

Install

npm install -g freelo-cli
# or
pnpm add -g freelo-cli

Requires Node.js 20.11 or newer.

Use

freelo --version           # prints the installed version
freelo --help              # shows available commands (human-readable)
freelo --introspect        # full command tree as JSON (agent-friendly)
freelo help <cmd> --output json   # JSON help for a single command or subtree

The CLI is agent-first: when stdout is not a TTY, every data-returning command emits a versioned JSON envelope ({ "schema": "freelo.<resource>.<op>/vN", "data": ... }). Pipe it into jq, capture it from a script, or hand it to your agent runner.

Use freelo auth login once to store credentials (env vars FREELO_API_KEY + FREELO_EMAIL work too — they take precedence and skip the keychain entirely, which is the recommended path for CI and agent workflows).

Commands

auth

• freelo auth login — Store credentials for a Freelo profile and verify them.
• freelo auth logout — Remove stored credentials for a Freelo profile.
• freelo auth whoami — Show the currently authenticated user.

config

• freelo config get <key> — Get the current value and source of a configuration key. Read-only keys (e.g. 'apiKey') return '[redacted]'.
• freelo config list — List all configuration keys with current values and sources.
• freelo config profiles — List all configured profiles.
• freelo config resolve — Print the merged effective configuration with optional per-leaf source annotation.
• freelo config set <key> <value> — Set a configuration key. Writable keys: output, color, profile, apiBaseUrl, verbose. Read-only keys (email, apiKey) must be updated via 'freelo auth login'.
• freelo config unset <key> — Remove a configuration key from the user conf store. Read-only keys cannot be unset via 'config'; use 'freelo auth logout' for credentials.
• freelo config use <profile> — Switch the active profile. The profile must already exist (created via 'freelo auth login'). No network call is made — use auth whoami to verify credentials afterward.

help

• freelo help [commandPath...] — Print the command tree as JSON (--output json) or as the same text as --help (default).

projects

• freelo projects list — List projects in the chosen scope. Default scope is 'owned'.
• freelo projects show <id> — Show one project's full detail, with optional side-cars.

The block above is generated from freelo --introspect by scripts/check-readme.mjs and verified in CI. Run pnpm fix:readme to refresh it after adding or changing a command.

The freelo help command (e.g. freelo help auth --output json) is intentionally not listed above — it's a meta-command that introspect excludes.

Develop

pnpm install
pnpm dev -- --version    # run the entry directly via tsx
pnpm build               # bundle to dist/freelo.js
pnpm test                # vitest
pnpm lint && pnpm typecheck
pnpm check:readme        # verify the autogen Commands block matches `freelo --introspect`
pnpm fix:readme          # rewrite the autogen Commands block in place

Conventional Commits are enforced by a commit-msg hook. Add a changeset (pnpm changeset) for any user-visible change.

Process

This repository uses an agentic SDLC. See .claude/docs/sdlc.md (interactive) and .claude/docs/autonomous-sdlc.md (autonomous via /auto).

License

MIT