hoja-cli 0.21.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. VERSION +1 -0
  2. google_workspace/__init__.py +19 -0
  3. google_workspace/client.py +253 -0
  4. google_workspace/config.py +39 -0
  5. google_workspace/errors.py +19 -0
  6. google_workspace/mcp_server.py +100 -0
  7. google_workspace/oauth.py +131 -0
  8. google_workspace/principal.py +83 -0
  9. google_workspace/py.typed +0 -0
  10. google_workspace/tools.py +64 -0
  11. google_workspace/writes.py +44 -0
  12. hoja/__init__.py +29 -0
  13. hoja/__main__.py +6 -0
  14. hoja/auth.py +42 -0
  15. hoja/cli.py +161 -0
  16. hoja/cli_state.py +55 -0
  17. hoja/client.py +268 -0
  18. hoja/commands/__init__.py +4 -0
  19. hoja/commands/auth_cmd.py +271 -0
  20. hoja/commands/comment.py +149 -0
  21. hoja/commands/cycle.py +75 -0
  22. hoja/commands/init.py +108 -0
  23. hoja/commands/issue.py +398 -0
  24. hoja/commands/label.py +163 -0
  25. hoja/commands/memory.py +240 -0
  26. hoja/commands/project.py +56 -0
  27. hoja/commands/raw.py +50 -0
  28. hoja/commands/team.py +102 -0
  29. hoja/commands/update.py +162 -0
  30. hoja/config.py +362 -0
  31. hoja/errors.py +107 -0
  32. hoja/filters.py +150 -0
  33. hoja/graphql/__init__.py +5 -0
  34. hoja/graphql/fragments.py +138 -0
  35. hoja/graphql/mutations.py +160 -0
  36. hoja/graphql/queries.py +245 -0
  37. hoja/mcp/__init__.py +27 -0
  38. hoja/mcp/content.py +151 -0
  39. hoja/mcp/prompts.py +298 -0
  40. hoja/mcp/resources.py +213 -0
  41. hoja/mcp/server.py +189 -0
  42. hoja/memory_board.py +370 -0
  43. hoja/models/__init__.py +37 -0
  44. hoja/models/base.py +64 -0
  45. hoja/models/cycle.py +32 -0
  46. hoja/models/enums.py +62 -0
  47. hoja/models/issue.py +99 -0
  48. hoja/models/label.py +17 -0
  49. hoja/models/project.py +60 -0
  50. hoja/models/team.py +31 -0
  51. hoja/models/user.py +32 -0
  52. hoja/models/workflow.py +65 -0
  53. hoja/output.py +410 -0
  54. hoja/skill_content/commands.md +222 -0
  55. hoja/skill_content/examples.md +193 -0
  56. hoja/skill_content/filters.md +101 -0
  57. hoja/skill_content/output-formats.md +92 -0
  58. hoja/skill_content/overview.md +123 -0
  59. hoja/skill_content/workflows.md +174 -0
  60. hoja_cli-0.21.4.dist-info/METADATA +279 -0
  61. hoja_cli-0.21.4.dist-info/RECORD +107 -0
  62. hoja_cli-0.21.4.dist-info/WHEEL +4 -0
  63. hoja_cli-0.21.4.dist-info/entry_points.txt +4 -0
  64. hoja_cli-0.21.4.dist-info/licenses/LICENSE +21 -0
  65. hoja_server/README.md +135 -0
  66. hoja_server/__init__.py +11 -0
  67. hoja_server/abac.py +116 -0
  68. hoja_server/agent_chat.py +280 -0
  69. hoja_server/agent_conversations.py +91 -0
  70. hoja_server/agent_durable.py +332 -0
  71. hoja_server/agent_prompt.py +117 -0
  72. hoja_server/agent_threads.py +96 -0
  73. hoja_server/agent_uploads.py +60 -0
  74. hoja_server/app.py +2189 -0
  75. hoja_server/cadence.py +231 -0
  76. hoja_server/cli.py +191 -0
  77. hoja_server/cloudflare_realtime.py +110 -0
  78. hoja_server/comment_policy.py +70 -0
  79. hoja_server/connector_actions.py +119 -0
  80. hoja_server/connectors_api.py +375 -0
  81. hoja_server/db.py +1816 -0
  82. hoja_server/denials.py +18 -0
  83. hoja_server/deployment.py +28 -0
  84. hoja_server/email_adapter.py +94 -0
  85. hoja_server/google_login.py +217 -0
  86. hoja_server/google_oidc.py +342 -0
  87. hoja_server/identity_transfer.py +210 -0
  88. hoja_server/mcp_oauth.py +623 -0
  89. hoja_server/mcp_tools.py +579 -0
  90. hoja_server/meeting_policy.py +179 -0
  91. hoja_server/meetings.py +1332 -0
  92. hoja_server/meetings_api.py +909 -0
  93. hoja_server/model_providers.py +205 -0
  94. hoja_server/realtime.py +690 -0
  95. hoja_server/resolvers.py +1281 -0
  96. hoja_server/schema.graphql +477 -0
  97. hoja_server/schema_sdl.py +8 -0
  98. hoja_server/secrets_box.py +39 -0
  99. hoja_server/signup_config.py +292 -0
  100. hoja_server/signup_gate.py +393 -0
  101. hoja_server/signup_policy.py +97 -0
  102. hoja_server/signup_store.py +577 -0
  103. hoja_server/store.py +2179 -0
  104. hoja_server/sync.py +249 -0
  105. hoja_server/tenant_context.py +131 -0
  106. hoja_server/turnstile.py +81 -0
  107. hoja_server/writer.py +1262 -0
@@ -0,0 +1,123 @@
1
+ # hoja — Overview
2
+
3
+ `hoja` is a type-safe command-line client for Linear (https://linear.app). Built on Pydantic v2 + httpx + Typer. Designed for humans, AI agents, CI pipelines, and shell scripts.
4
+
5
+ ## When to reach for hoja
6
+
7
+ Use `hoja` via the **Bash tool** whenever a task touches Linear:
8
+
9
+ - Anything mentioning a Linear identifier like `ENG-35`, `ENG-123`, or `<TEAM>-<N>`.
10
+ - "Create / open / file / log / track an issue."
11
+ - "Assign / move / triage / comment on" an issue.
12
+ - "What's in the current cycle / sprint?"
13
+ - "Which Linear projects exist?"
14
+ - "Who is working on X?"
15
+ - Any request for status, backlog, label, or workflow state operations.
16
+
17
+ ## Why CLI over raw API
18
+
19
+ - Auth, retries, rate-limit handling, pagination, and Pydantic validation are already implemented in `hoja`. You do not need to reproduce them.
20
+ - Mutation safety: `--dry-run` previews destructive operations.
21
+ - Composition: every command supports `--output {human|json|yaml|md|plain|ids}` so you can pipe to `jq`, `xargs`, or another shell command.
22
+ - Stability: the CLI's command surface is versioned and tested with 36+ end-to-end tests against the live API.
23
+
24
+ ## Behavioral rules (read these before invoking)
25
+
26
+ 1. **Verify auth first in a fresh shell:** `hoja me`. If it fails, stop and surface the auth error to the user before any mutation.
27
+ 2. **Read the memory board before starting work.** Run `hoja memory remind` first to load forced rules and recent project context. If you learn something useful, add it with `hoja memory add --title "..." --body "..."`. Stale entries auto-heal after 30 days.
28
+ 3. **Discover accounts before assuming defaults.** When working across multiple Linear organizations, run `hoja -o json auth accounts` to see available accounts and their org names. Use `--account <name>` for one-off switches or `hoja auth workspace` to verify auto-detection.
29
+ 3. **Search before create.** `hoja issue search "<query>"` prevents duplicate issues. Always run this when the user says "create an issue about X" unless they already gave you an explicit identifier.
30
+ 4. **Use `--output json` when piping or programmatically reading.** `--output human` is for terminal display only.
31
+ 5. **Linear identifiers are case-sensitive.** Use `ENG-35`, never `eng-35`.
32
+ 6. **Use `--dry-run` on mutations** when the user's intent is ambiguous or destructive.
33
+ 7. **Prefer dedicated subcommands over `raw query`.** `raw query` is an escape hatch for unsupported GraphQL operations only.
34
+ 8. **Chain via the shell, not Python.** For multi-step workflows (create + assign + comment), call `hoja` three times — do not write Python wrappers around the GraphQL API.
35
+ 9. **Filter at the API, not in shell.** `hoja issue list --assignee me --state "In Progress"` is faster and cleaner than `hoja issue list | jq`.
36
+ 10. **Never log or echo the token.** The CLI masks it automatically; do not print `$HOJA_TOKEN` in your shell output.
37
+ 11. **`hoja issue delete` does NOT exist.** The Linear-compatible API has no issue hard delete. Use a state transition (e.g., `cancel` or `archive` workflow state) instead.
38
+
39
+ ## Command tree (one-liner reference)
40
+
41
+ ```
42
+ hoja me # current user
43
+ hoja auth status # who am I authed as?
44
+ hoja auth accounts # list all accounts
45
+ hoja auth add <NAME> --token <T> # add an account
46
+ hoja auth switch <NAME> # set default
47
+ hoja auth workspace # show current workspace + mapped account
48
+ hoja init # write config file
49
+ hoja update # self-update from PyPI
50
+
51
+ hoja memory remind # read memory board before work
52
+ hoja memory add --title "..." --body "..." # add what you learned
53
+ hoja memory list # all entries
54
+ hoja memory heal # remove stale community entries
55
+
56
+ hoja team list
57
+ hoja team get <KEY> # e.g. ENG
58
+ hoja team states <KEY> # workflow states for a team
59
+ hoja team members <KEY>
60
+
61
+ hoja issue list [filters...]
62
+ hoja issue get <ID> # e.g. ENG-35
63
+ hoja issue create --team <KEY> --title "..." [--description ...] [--priority N] [--assignee NAME] [--label "a,b"]
64
+ hoja issue update <ID> [--title ...] [--description ...] [--priority N]
65
+ hoja issue state <ID> "<STATE_NAME>" # e.g. "In Progress"
66
+ hoja issue assign <ID> <USER_NAME>
67
+ hoja issue prio <ID> <N> # 0=none 1=urgent 2=high 3=med 4=low
68
+ hoja issue url <ID>
69
+ hoja issue search "<text>"
70
+
71
+ hoja project list
72
+ hoja project get <ID_OR_SLUG>
73
+
74
+ hoja cycle current <TEAM_KEY>
75
+ hoja cycle list <TEAM_KEY>
76
+
77
+ hoja comment list <ISSUE_ID> [-n N]
78
+ hoja comment add <ISSUE_ID> "..." # body positional; omit to read stdin
79
+ hoja comment edit <COMMENT_ID> "..."
80
+ hoja comment delete <COMMENT_ID>
81
+
82
+ hoja label list [--team <KEY>]
83
+ hoja label create --team <KEY> --name "..." [--color "#hex"]
84
+ hoja label delete <LABEL_ID>
85
+
86
+ hoja raw query "<GraphQL string>" # escape hatch
87
+ ```
88
+
89
+ ## Global flags
90
+
91
+ - `--token <TOKEN>` — override env var. Use only when needed.
92
+ - `--account <NAME>` — one-off account override. Run `auth accounts` first to discover names.
93
+ - `--output, -o {human,json,yaml,md,plain,ids}` — output format.
94
+ - `--verbose, -v` — log GraphQL operations to stderr (token redacted).
95
+ - `--quiet, -q` — suppress non-essential output.
96
+ - `--no-color` — disable ANSI colors.
97
+ - `--dry-run` — print mutations without executing.
98
+ - `--timeout <SECONDS>` — HTTP timeout (default 30).
99
+ - `--version` — print version.
100
+
101
+ ## Exit codes (scriptable)
102
+
103
+ | Code | Meaning |
104
+ |------|---------|
105
+ | 0 | Success |
106
+ | 1 | Generic error |
107
+ | 2 | Typer / usage error |
108
+ | 3 | AuthError — no token or rejected token |
109
+ | 4 | NotFoundError — issue/team/etc not found |
110
+ | 5 | NetworkError |
111
+ | 6 | InvalidInput — validation error |
112
+ | 7 | RateLimitError |
113
+ | 8 | APIError — GraphQL or server |
114
+
115
+ Use these in shell scripts: `hoja issue get ENG-9999 || [ $? -eq 4 ] && echo "not found"`.
116
+
117
+ ## See also
118
+
119
+ - `commands.md` — full noun/verb breakdown with examples
120
+ - `workflows.md` — common multi-step patterns (triage, standup, hand-off)
121
+ - `filters.md` — `issue list` filter DSL
122
+ - `output-formats.md` — how to choose `--output`
123
+ - `examples.md` — copy-pasteable real-world recipes
@@ -0,0 +1,174 @@
1
+ # hoja — Workflow Patterns
2
+
3
+ Multi-step patterns that combine `hoja` commands. **Always chain via the shell.** Do not write Python wrappers — that's what the CLI exists to avoid.
4
+
5
+ ---
6
+
7
+ ## 1. Triage — claim unassigned issues
8
+
9
+ When a user says "triage Team ENG" or "clean up the inbox":
10
+
11
+ ```bash
12
+ # Step 1 — list unassigned, recently created
13
+ hoja issue list --team ENG --no-assignee --state "Todo" -n 20
14
+
15
+ # Step 2 — for each issue you want to act on, get details
16
+ hoja issue get ENG-42
17
+
18
+ # Step 3 — assign + label + (optionally) move state
19
+ hoja issue assign ENG-42 me
20
+ hoja issue update ENG-42 --label "infra"
21
+ hoja issue state ENG-42 "In Progress"
22
+ ```
23
+
24
+ **Behavioral rule:** during triage, never bulk-modify without showing the user the list first (with `-o human`). Confirm intent before mutations.
25
+
26
+ ---
27
+
28
+ ## 2. Daily standup — what am I working on?
29
+
30
+ ```bash
31
+ hoja issue list --assignee me --state "In Progress" -n 20
32
+ hoja issue list --assignee me --state "In Review" -n 20
33
+ ```
34
+
35
+ Render in markdown for the user:
36
+ ```bash
37
+ hoja -o md issue list --assignee me --state "In Progress"
38
+ ```
39
+
40
+ ---
41
+
42
+ ## 3. Create an issue from an error trace
43
+
44
+ When the user pastes a stack trace and says "log this":
45
+
46
+ ```bash
47
+ # Step 1 — search first to avoid duplicates
48
+ hoja issue search "TypeError viewer" -n 5
49
+
50
+ # Step 2 — if no match, create
51
+ hoja issue create \
52
+ --team ENG \
53
+ --title "TypeError: viewer is undefined on /dashboard" \
54
+ --description "$(cat error.log)" \
55
+ --priority 2 \
56
+ --label "bug"
57
+ ```
58
+
59
+ **Behavioral rule:** ALWAYS search before create unless the user has explicitly said "create a new one even if duplicates exist."
60
+
61
+ ---
62
+
63
+ ## 4. Cycle health — what's at risk in the current sprint?
64
+
65
+ ```bash
66
+ # Step 1 — what cycle are we in?
67
+ hoja cycle current ENG
68
+
69
+ # Step 2 — issues in current cycle, grouped by state
70
+ hoja -o json issue list --cycle current --team ENG | jq 'group_by(.state.name) | map({state: .[0].state.name, count: length, items: map(.identifier)})'
71
+
72
+ # Step 3 — blockers
73
+ hoja issue list --cycle current --team ENG --label "blocked"
74
+ ```
75
+
76
+ ---
77
+
78
+ ## 5. Hand off an issue to another teammate
79
+
80
+ Three commands, in order, with one comment trail:
81
+
82
+ ```bash
83
+ hoja issue assign ENG-35 "Bob"
84
+ hoja issue state ENG-35 "In Review"
85
+ hoja comment add ENG-35 "Handing off to @bob — context: see PR #1234"
86
+ ```
87
+
88
+ **Behavioral rule:** always add a comment when handing off. A bare reassignment without context creates ambiguity downstream.
89
+
90
+ ---
91
+
92
+ ## 6. Bulk re-label (xargs pattern)
93
+
94
+ To re-label every issue carrying a deprecated label:
95
+
96
+ ```bash
97
+ # Step 1 — preview the target set
98
+ hoja -o ids issue list --label "old-name" -n 100
99
+
100
+ # Step 2 — for each id, run the mutation
101
+ hoja -o ids issue list --label "old-name" -n 100 \
102
+ | xargs -I{} hoja issue update {} --label "new-name"
103
+ ```
104
+
105
+ `-o ids` emits one identifier per line, perfect for `xargs`.
106
+
107
+ ---
108
+
109
+ ## 7. Investigate one issue end-to-end
110
+
111
+ ```bash
112
+ # Full payload
113
+ hoja -o json issue get ENG-35
114
+
115
+ # Comments
116
+ hoja comment list ENG-35
117
+
118
+ # Related issues by label
119
+ LABEL=$(hoja -o json issue get ENG-35 | jq -r '.labels[0].name')
120
+ hoja issue list --label "$LABEL" -n 10
121
+ ```
122
+
123
+ ---
124
+
125
+ ## 8. Create issue and link to a PR
126
+
127
+ ```bash
128
+ ISSUE=$(hoja -o json issue create --team ENG --title "Add retry to API client" --priority 3 | jq -r '.identifier')
129
+ echo "Created $ISSUE"
130
+ echo "Linear: $(hoja issue url $ISSUE)"
131
+ # Now reference $ISSUE in your PR title or commit message:
132
+ # hoja convention: include the identifier in the branch name (e.g. ENG-35-add-retry)
133
+ ```
134
+
135
+ ---
136
+
137
+ ## 9. Weekly review — what shipped?
138
+
139
+ ```bash
140
+ hoja -o md issue list --assignee me --state "Done" --updated-after $(date -d "7 days ago" +%Y-%m-%d) -n 50
141
+ ```
142
+
143
+ ---
144
+
145
+ ## 10. Comment from CI output
146
+
147
+ In a CI script, post failure details to the related Linear issue:
148
+
149
+ ```bash
150
+ ISSUE_ID=$(git log -1 --pretty=%B | grep -oE 'ENG-[0-9]+' | head -1)
151
+ if [ -n "$ISSUE_ID" ]; then
152
+ pytest 2>&1 | tail -50 | hoja comment add "$ISSUE_ID"
153
+ fi
154
+ ```
155
+
156
+ ---
157
+
158
+ ## Anti-patterns (do NOT do these)
159
+
160
+ | Don't | Why | Instead |
161
+ |---|---|---|
162
+ | Write a Python script calling the GraphQL API directly | hoja already handles auth/retries/pagination/validation | Use `hoja` in the shell |
163
+ | Loop in shell when filters would do the job | One API call vs N | Use `hoja issue list --filter ...` |
164
+ | `hoja issue list \| jq` to filter on team or state | Server-side filters are faster and produce smaller payloads | Use `--team`, `--state`, `--assignee` |
165
+ | Hardcode tokens in scripts | Leak risk | Use the `$HOJA_TOKEN` env var (deprecated `$LINEAR_TOKEN` still works), never `--token <real>` |
166
+ | Use `raw query` for things the wrapper supports | Inconsistent errors, no Pydantic validation | Use dedicated commands |
167
+ | `hoja issue delete` | Does not exist | Use state transition or archive workflow |
168
+ | Bulk mutate without `--dry-run` first when uncertain | One typo = many bad writes | Always preview with `--dry-run` |
169
+
170
+ ## See also
171
+
172
+ - `commands.md` — verb-by-verb reference
173
+ - `filters.md` — `issue list` filter DSL
174
+ - `examples.md` — short copy-paste recipes
@@ -0,0 +1,279 @@
1
+ Metadata-Version: 2.5
2
+ Name: hoja-cli
3
+ Version: 0.21.4
4
+ Summary: Hoja CLI and local server: self-hosted, offline-first, agent-native work management with a Linear-compatible GraphQL API
5
+ Project-URL: Homepage, https://github.com/hoja-work/hoja
6
+ Project-URL: Repository, https://github.com/hoja-work/hoja
7
+ Project-URL: Documentation, https://github.com/hoja-work/hoja/blob/main/docs/DESIGN.md
8
+ Project-URL: Issues, https://github.com/hoja-work/hoja/issues
9
+ Project-URL: Changelog, https://github.com/hoja-work/hoja/blob/main/CHANGELOG.md
10
+ Maintainer: Rinadelph
11
+ License: MIT
12
+ License-File: LICENSE
13
+ Keywords: cli,graphql,hoja,issue-tracker,linear,pydantic,work-management
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Software Development
24
+ Classifier: Topic :: Utilities
25
+ Requires-Python: >=3.10
26
+ Requires-Dist: cryptography<60,>=42
27
+ Requires-Dist: httpx<1.0,>=0.27
28
+ Requires-Dist: pydantic<3.0,>=2.10
29
+ Requires-Dist: rich<16.0,>=15.0.0
30
+ Requires-Dist: tomli-w>=1.0
31
+ Requires-Dist: tomli>=2.0; python_version < '3.11'
32
+ Requires-Dist: typer<1.0,>=0.15
33
+ Provides-Extra: agent
34
+ Requires-Dist: google-workspace-connector; extra == 'agent'
35
+ Requires-Dist: pydantic-ai-slim[dbos,mcp,openai]<3.0,>=2.54; extra == 'agent'
36
+ Provides-Extra: dev
37
+ Requires-Dist: mypy>=1.13; extra == 'dev'
38
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
39
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
40
+ Requires-Dist: pytest>=8.0; extra == 'dev'
41
+ Requires-Dist: respx>=0.21; extra == 'dev'
42
+ Requires-Dist: ruff>=0.7; extra == 'dev'
43
+ Provides-Extra: mcp
44
+ Requires-Dist: mcp<3.0.0,>=2.2.0; extra == 'mcp'
45
+ Provides-Extra: saas
46
+ Requires-Dist: asyncpg>=0.29; extra == 'saas'
47
+ Provides-Extra: server
48
+ Requires-Dist: aiosqlite>=0.20; extra == 'server'
49
+ Requires-Dist: ariadne>=0.23; extra == 'server'
50
+ Requires-Dist: fastapi>=0.115; extra == 'server'
51
+ Requires-Dist: psycopg[binary]>=3.2; extra == 'server'
52
+ Requires-Dist: sqlalchemy>=2.0; extra == 'server'
53
+ Requires-Dist: uvicorn[standard]>=0.30; extra == 'server'
54
+ Description-Content-Type: text/markdown
55
+
56
+ # Hoja
57
+
58
+ **A self-hosted workspace for issues, projects, cycles, and team work.** Hoja includes a browser UI and a Python CLI. It can run against its own SQLite or PostgreSQL-backed service; the GraphQL API also implements a Linear-compatible surface for clients that use it.
59
+
60
+ The Python package is published on PyPI as **`hoja-cli`** and installs the
61
+ commands **`hoja`**, **`hoja-serve`**, and the optional **`hoja-mcp`**. The
62
+ distribution carries the `-cli` suffix because the `hoja` project on PyPI is
63
+ unrelated software; install `hoja-cli`, then run `hoja`.
64
+
65
+ ## What you can do
66
+
67
+ - Sign in to a workspace, switch between memberships, and create workspaces, teams, and members.
68
+ - Create, search, filter, assign, and update issues; browse team boards and cycles; open issue details and comment.
69
+ - Organize projects, review project issues and updates, and manage initiatives.
70
+ - Use Inbox for future issue notifications, with unread/read and archive controls. Existing historical events are not backfilled.
71
+ - Save issue and project views in the browser. These views are local to that browser, not shared workspace records.
72
+ - Use the CLI for shell workflows and automation. Responses are validated models; `--output json` and `--output ids` are suitable for scripts.
73
+
74
+ Hoja does not require Linear Cloud. The API uses Linear-compatible GraphQL names and authenticates with `HOJA_TOKEN` / `HOJA_API_URL`, so compatible clients can target a Hoja server. The former `LINEAR_TOKEN` and `LINEAR_API_URL` names are still read as deprecated aliases (the `HOJA_*` variable wins when both are set). Compatibility does not mean every Linear feature is implemented. Unsupported screens or controls are presented as unavailable rather than simulated as working.
75
+
76
+ ## Run the workspace locally with Docker
77
+
78
+ This is the recommended way to try Hoja locally. Docker Compose builds the web
79
+ app and starts it with PostgreSQL. You will need Docker Desktop (or Docker
80
+ Engine with the Compose plugin) installed and running. The first build needs
81
+ internet access to download the base images and frontend/Python dependencies.
82
+
83
+ 1. In the repository root, create a `.env` file with a password for the local
84
+ PostgreSQL database:
85
+
86
+ ```dotenv
87
+ POSTGRES_PASSWORD=replace-with-a-long-random-password
88
+ ```
89
+
90
+ Keep this file private; do not commit it. Compose currently has a
91
+ development fallback password, so setting your own avoids relying on that
92
+ default. If port `8787` is already in use, add `HOJA_PORT=8788` to this
93
+ same file and use port 8788 in the browser URL below.
94
+
95
+ 2. Build and start the services:
96
+
97
+ ```bash
98
+ docker compose up --build -d
99
+ ```
100
+
101
+ The first build can take a few minutes. Compose waits for PostgreSQL to
102
+ become healthy; the app applies database migrations when it starts.
103
+
104
+ 3. Open [http://localhost:8787](http://localhost:8787) (or the port you chose).
105
+ On a fresh database, the browser wizard guides you through choosing a
106
+ language preference, creating your admin profile/password, and naming your
107
+ workspace and first team. Existing databases go to the sign-in screen.
108
+
109
+ To confirm the server responds before opening the UI, run
110
+ `curl -i http://localhost:8787/health`; a healthy server returns HTTP 200
111
+ with a JSON status body. The `/ready` endpoint reports whether the database
112
+ schema is ready; if it is not, inspect the app logs below.
113
+
114
+ 4. When prompted, optionally add teammates. Hoja creates each member and
115
+ provides a copyable invite link. Share it with that person; they can open it,
116
+ enter the invited email, and set their password. Links expire after 72 hours
117
+ and work once. Hoja does not email invitations. You can skip this and invite
118
+ people later from **Members**. The finish step can show the admin API key for
119
+ CLI setup. Browser sign-in uses an HttpOnly cookie.
120
+
121
+ ### Stop, restart, and reset
122
+
123
+ Stop the containers while keeping your workspace data:
124
+
125
+ ```bash
126
+ docker compose down
127
+ ```
128
+
129
+ Start them again later with `docker compose up -d`. PostgreSQL data is stored
130
+ in the named `hoja-postgres` volume and survives ordinary container stops
131
+ and rebuilds. To permanently delete the local database and all demo data, use
132
+ `docker compose down -v`; this is destructive and the data cannot be recovered
133
+ without a backup.
134
+
135
+ ### Troubleshooting
136
+
137
+ - **Docker is unavailable:** start Docker Desktop / Docker Engine, then retry.
138
+ - **`docker compose` is not a command:** install or enable the Docker Compose
139
+ v2 plugin (included with current Docker Desktop), then verify with
140
+ `docker compose version`. This guide uses the `docker compose` subcommand,
141
+ not the legacy standalone `docker-compose` command.
142
+ - **Port is already allocated:** set `HOJA_PORT=8788` in `.env` and browse
143
+ to `http://localhost:8788`.
144
+ - **The app cannot connect to PostgreSQL:** check `docker compose ps` and
145
+ `docker compose logs db app`; Compose starts the app only after the database
146
+ health check passes. Correct `.env` changes may require recreating services
147
+ with `docker compose up -d`.
148
+ - **The app starts but is not ready:** check `docker compose logs app db` and
149
+ `curl -i http://localhost:8787/ready`. The app runs migrations at startup;
150
+ wait for the app container to finish starting, then retry. Do not remove the
151
+ PostgreSQL volume as a first troubleshooting step.
152
+ - **The wizard reports that the instance is already set up:** use the existing
153
+ sign-in screen. Bootstrap is only available on a fresh database. To restart a
154
+ disposable demo from scratch, use the destructive `docker compose down -v`
155
+ command above.
156
+
157
+ This Compose setup is intended for a local demo. The fallback database password
158
+ in `docker-compose.yml` is for development only; set a private password in
159
+ `.env` before using the configuration beyond a disposable local instance. Use
160
+ letters and numbers in that password because Compose interpolates it into the
161
+ PostgreSQL connection URL.
162
+
163
+ See [deployment](docs/DEPLOYMENT.md) for database setup, migrations, readiness
164
+ checks, and multi-organization token provisioning.
165
+
166
+ For an isolated SQLite instance instead:
167
+
168
+ ```bash
169
+ python -m pip install 'hoja-cli[server]'
170
+ hoja-serve seed --tenant local --org "Local Workspace" \
171
+ --org-key local --team-key ENG --email user@example.test
172
+ hoja-serve serve --tenant local --host 127.0.0.1 --port 8787
173
+ ```
174
+
175
+ ## Use the CLI
176
+
177
+ Install the CLI from PyPI or from a checkout:
178
+
179
+ ```bash
180
+ python -m pip install hoja-cli
181
+ # or, isolated from your system Python:
182
+ uv tool install hoja-cli
183
+ # or, from this repository:
184
+ uv sync --extra dev --extra server
185
+ ```
186
+
187
+ Configure an account in `~/.config/hoja/config.toml`:
188
+
189
+ ```toml
190
+ [accounts.local]
191
+ base_url = "http://127.0.0.1:8787/graphql"
192
+ token_env = "HOJA_TOKEN"
193
+
194
+ [defaults]
195
+ default_account = "local"
196
+ ```
197
+
198
+ Export the token as `HOJA_TOKEN` (or choose a different `token_env` for the
199
+ account), then try:
200
+
201
+ ```bash
202
+ hoja me
203
+ hoja team list
204
+ hoja issue list --assignee me
205
+ hoja issue create --team ENG --title "Review onboarding flow"
206
+ hoja -o json issue list --state Todo
207
+ ```
208
+
209
+ The CLI also supports projects, cycles, comments, labels, raw GraphQL queries, and dry-run previews for supported mutations. Run `hoja --help` or `hoja <command> --help` for the current command and option list. Clients written against the Linear-compatible surface can point at Hoja with `LINEAR_TOKEN` and `LINEAR_API_URL`; those names remain accepted as deprecated aliases of `HOJA_TOKEN` and `HOJA_API_URL`.
210
+
211
+ ## Agent integrations
212
+
213
+ The optional MCP server provides one guide tool, seven read-only resources, and six workflow prompts. It does not expose mutation tools; make changes through the CLI.
214
+
215
+ ```bash
216
+ python -m pip install 'hoja-cli[mcp]'
217
+ ```
218
+
219
+ Register `hoja-mcp` as a stdio MCP server in your client, passing the needed token through that client's environment configuration. The server reads the same account configuration as the CLI. See [the MCP section below](#mcp-server-setup) for a complete example.
220
+
221
+ The repository also includes an installable agent skill:
222
+
223
+ ```bash
224
+ bash skills/install.sh --claude-only
225
+ ```
226
+
227
+ It installs the `skills/hoja` instructions into the selected agent skill directory; `--copy` copies rather than symlinks.
228
+
229
+ ## MCP server setup
230
+
231
+ Install the optional MCP dependency alongside the CLI:
232
+
233
+ ```bash
234
+ python -m pip install 'hoja-cli[mcp]'
235
+ ```
236
+
237
+ For Claude Desktop, add a server entry to its MCP configuration. Use an absolute
238
+ executable path if the GUI does not inherit your shell `PATH`:
239
+
240
+ ```json
241
+ {
242
+ "mcpServers": {
243
+ "hoja": {
244
+ "command": "/absolute/path/to/hoja-mcp",
245
+ "env": {
246
+ "HOJA_TOKEN": "<workspace-token>"
247
+ }
248
+ }
249
+ }
250
+ }
251
+ ```
252
+
253
+ Replace the command path with the result of `which hoja-mcp`. If the selected
254
+ account sets a custom `token_env`, pass that variable instead. The MCP server
255
+ provides one guide tool, seven read-only resources, and six workflow prompts;
256
+ it does not provide mutation tools.
257
+
258
+ ## Development
259
+
260
+ Python 3.10 or newer is required. Install development and backend dependencies, then run the tests:
261
+
262
+ ```bash
263
+ uv sync --extra dev --extra server
264
+ uv run pytest
265
+ ```
266
+
267
+ Build the browser app with `npm ci && npm run build` in `frontend/`. The local backend integration script is `bash scripts/e2e-local-backend.sh`; it uses a disposable local database. The live API CLI matrix in `scripts/e2e-test.sh` requires `HOJA_TOKEN`, `HOJA_TEST_TEAM`, and `HOJA_TEST_ISSUE`.
268
+
269
+ Contributor and agent operations, including the documentation contract, are in
270
+ [AGENTS.md](AGENTS.md). Run `python3 scripts/check_docs.py` before submitting
271
+ changes that add or modify documentation.
272
+
273
+ Product architecture is described in [Design](docs/DESIGN.md); deployment instructions are in [Deployment](docs/DEPLOYMENT.md). The [changelog](CHANGELOG.md) records release-level behavior changes.
274
+
275
+ ## First run in the browser
276
+
277
+ On a fresh database, open Hoja in your browser to start the setup wizard. Choose a language preference (English is currently available), create your admin profile and password, then name your workspace and first team. You’ll be signed in when setup completes. Existing workspaces continue to show the sign-in screen.
278
+
279
+ The wizard can create teammates and show each generated API key once for you to share. It does not send invitation email. Save or share each key securely; it is not shown again. You can skip invitations and add people later from **Members**. Your admin API key is available once in the finish step for CLI configuration.