Weeks CLI

Install

Homebrew is the preferred path on macOS and Linux:

brew tap weeks-app/tap
brew trust weeks-app/tap
brew install weeks

For shells without Homebrew:

curl -fsSL https://about.weeks.app/install.sh | sh

The installer downloads the current release from GitHub, verifies the archive against the published checksum file, and installs weeks into ~/.local/bin. Set WEEKS_INSTALL_DIR to choose another directory.

The packaged install paths currently provide v0.1.3. The hosted login, local folder storage and defaults, and staffing read commands documented below are merged on main but are not in that release yet. To try that unreleased surface, build the current development tip:

go install github.com/weeks-app/weeks-cli/cmd/weeks@main

Go users who want the latest published release can build it from source:

go install github.com/weeks-app/weeks-cli/cmd/weeks@latest

Set up

weeks setup --profile default
weeks doctor --json

In a terminal, weeks setup creates or selects the default profile, installs the embedded agent skill for Claude Code, and starts the device login flow. Use --base-url or --client-id for a local or self-hosted installation, and --skip-login when setup should only write the profile and skill. In JSON or other non-interactive runs, setup starts login only when you pass --login.

Authenticate

weeks profile set acme --base-url https://weeks.app --default
weeks auth login
weeks doctor --json

weeks auth login uses the OAuth device flow by default. It prints a code and a browser URL, so it works from SSH sessions, containers, and agent panes. New logins also store a refresh token. API-backed read commands automatically refresh access tokens when they are close to expiring. Credentials without a refresh token remain usable while their access token is valid, but need a new weeks auth login in the same profile and storage scope before they can refresh.

Sign in from a terminal The CLI device flow with browser approval and weeks auth status verification. Open the interaction

Storage and folder defaults

By default, weeks stores profiles and file-backed credentials in ./.weeks/ for the folder where the command runs. That keeps one project’s agent from silently reusing another project’s login. Use weeks --global <command> when you deliberately want the user-wide config under $XDG_CONFIG_HOME/weeks or ~/.config/weeks; global credentials prefer the system keyring and fall back to a file. WEEKS_CONFIG_DIR takes precedence over both and selects an environment-provided directory with file-backed credentials.

Every normal JSON envelope includes profile, base_url, config_scope, and config_dir in context. Styled terminal output shows the same invocation facts under Using.

Local folders can remember the team and space used by read commands:

weeks defaults show
weeks defaults set
weeks defaults set --team <team-id> --space <space-id>
weeks defaults clear

In a terminal, weeks defaults set lets you choose from accessible teams and spaces. In scripts, pass --team to weeks defaults set; add --space there so later weeks plans list commands can run without --space. Folder defaults are available only in true local scope: the CLI rejects defaults with --global or WEEKS_CONFIG_DIR.

Basic reads

weeks teams list
weeks teams view <team-id>

weeks spaces list
weeks spaces list --team <team-id>
weeks spaces view <space-id> --include overview

weeks people list
weeks people list --space <space-id>
weeks people view <space-person-id>

weeks planning-contexts list
weeks planning-contexts list --space <space-id>
weeks planning-contexts view <planning-context-id>

weeks plans list
weeks plans list --space <space-id>
weeks plans view <plan-id> --include snapshot

Use the typed IDs returned by the API, such as team_..., space_..., space_person_..., planning_context_..., planning_context_value_..., and plan_.... Planning-context value IDs appear inside planning-context reads. weeks spaces list resolves its team from an explicit --team, then the folder default, then a sole accessible team. weeks people list, weeks planning-contexts list, and weeks plans list resolve their space from --space or the folder default. view returns one API resource, and JSON output preserves the resource shape returned by the server. For plan reads, styled output expands requested plan collections into readable item sections rather than reducing them to collection counts. Other resource types still summarize nested collections by count.

Include scopes are passed to the API. overview adds counts, people, and plans to a space; snapshot adds the plan’s people, jobs, inboxes, slots, assignments, and routes. Resolved planning hints are separate: use --include snapshot,planning_hints when you need both.

Output formats

At a terminal, weeks uses a compact, human-readable view. Pass --styled when a person will read redirected or captured output. Pass --json for the stable envelope used by scripts and agents. Both formats describe the same API response; JSON also keeps the structured summary, breadcrumbs, and invocation context.

This is the same weeks teams list response in both formats:

✓ 1 teams.

Using
  profile       (none)
  config store  env (/tmp/weeks-cli-config)
  base url      https://weeks.app

team_aAVvAm  Weeks Demo Team

Next
  weeks teams view <team-id>           Fetch one team
  weeks spaces list --team <team-id>   List spaces inside a team

{
  "ok": true,
  "data": [
    {
      "created_at": "2026-08-28T18:00:00Z",
      "id": "team_aAVvAm",
      "name": "Weeks Demo Team",
      "time_zone": "Berlin",
      "locale": "en",
      "updated_at": "2026-08-28T18:00:00Z"
    }
  ],
  "summary": "1 teams.",
  "breadcrumbs": [
    {
      "action": "view",
      "cmd": "weeks teams view <team-id>",
      "description": "Fetch one team"
    },
    {
      "action": "spaces",
      "cmd": "weeks spaces list --team <team-id>",
      "description": "List spaces inside a team"
    }
  ],
  "context": {
    "base_url": "https://weeks.app",
    "config_dir": "/tmp/weeks-cli-config",
    "config_scope": "env",
    "profile": null
  }
}

Discover commands

The CLI publishes its own command catalog:

weeks commands --json
weeks commands --json --flat
weeks <command> --help --agent
weeks skill

The catalog is the source of truth for what the installed binary can do. The CLI is still early: authentication, profiles, diagnostics, discovery, setup, and basic team, space, people, planning-contexts, and plan reads have shipped; most scheduling commands and all writes have not.

The static docs should generate command reference pages from that catalog instead of copying command descriptions by hand.

Environments

Use profiles for different Weeks installations:

weeks profile set local --base-url http://localhost:3000
weeks --profile local doctor --json

WEEKS_BASE_URL can override the profile for a single command.

Coverage

Each shipped staffing command should be tied to the same interaction it automates in the product and to the API endpoint it calls. The coverage page tracks that relationship as the CLI grows.