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.
- VERSION +1 -0
- google_workspace/__init__.py +19 -0
- google_workspace/client.py +253 -0
- google_workspace/config.py +39 -0
- google_workspace/errors.py +19 -0
- google_workspace/mcp_server.py +100 -0
- google_workspace/oauth.py +131 -0
- google_workspace/principal.py +83 -0
- google_workspace/py.typed +0 -0
- google_workspace/tools.py +64 -0
- google_workspace/writes.py +44 -0
- hoja/__init__.py +29 -0
- hoja/__main__.py +6 -0
- hoja/auth.py +42 -0
- hoja/cli.py +161 -0
- hoja/cli_state.py +55 -0
- hoja/client.py +268 -0
- hoja/commands/__init__.py +4 -0
- hoja/commands/auth_cmd.py +271 -0
- hoja/commands/comment.py +149 -0
- hoja/commands/cycle.py +75 -0
- hoja/commands/init.py +108 -0
- hoja/commands/issue.py +398 -0
- hoja/commands/label.py +163 -0
- hoja/commands/memory.py +240 -0
- hoja/commands/project.py +56 -0
- hoja/commands/raw.py +50 -0
- hoja/commands/team.py +102 -0
- hoja/commands/update.py +162 -0
- hoja/config.py +362 -0
- hoja/errors.py +107 -0
- hoja/filters.py +150 -0
- hoja/graphql/__init__.py +5 -0
- hoja/graphql/fragments.py +138 -0
- hoja/graphql/mutations.py +160 -0
- hoja/graphql/queries.py +245 -0
- hoja/mcp/__init__.py +27 -0
- hoja/mcp/content.py +151 -0
- hoja/mcp/prompts.py +298 -0
- hoja/mcp/resources.py +213 -0
- hoja/mcp/server.py +189 -0
- hoja/memory_board.py +370 -0
- hoja/models/__init__.py +37 -0
- hoja/models/base.py +64 -0
- hoja/models/cycle.py +32 -0
- hoja/models/enums.py +62 -0
- hoja/models/issue.py +99 -0
- hoja/models/label.py +17 -0
- hoja/models/project.py +60 -0
- hoja/models/team.py +31 -0
- hoja/models/user.py +32 -0
- hoja/models/workflow.py +65 -0
- hoja/output.py +410 -0
- hoja/skill_content/commands.md +222 -0
- hoja/skill_content/examples.md +193 -0
- hoja/skill_content/filters.md +101 -0
- hoja/skill_content/output-formats.md +92 -0
- hoja/skill_content/overview.md +123 -0
- hoja/skill_content/workflows.md +174 -0
- hoja_cli-0.21.4.dist-info/METADATA +279 -0
- hoja_cli-0.21.4.dist-info/RECORD +107 -0
- hoja_cli-0.21.4.dist-info/WHEEL +4 -0
- hoja_cli-0.21.4.dist-info/entry_points.txt +4 -0
- hoja_cli-0.21.4.dist-info/licenses/LICENSE +21 -0
- hoja_server/README.md +135 -0
- hoja_server/__init__.py +11 -0
- hoja_server/abac.py +116 -0
- hoja_server/agent_chat.py +280 -0
- hoja_server/agent_conversations.py +91 -0
- hoja_server/agent_durable.py +332 -0
- hoja_server/agent_prompt.py +117 -0
- hoja_server/agent_threads.py +96 -0
- hoja_server/agent_uploads.py +60 -0
- hoja_server/app.py +2189 -0
- hoja_server/cadence.py +231 -0
- hoja_server/cli.py +191 -0
- hoja_server/cloudflare_realtime.py +110 -0
- hoja_server/comment_policy.py +70 -0
- hoja_server/connector_actions.py +119 -0
- hoja_server/connectors_api.py +375 -0
- hoja_server/db.py +1816 -0
- hoja_server/denials.py +18 -0
- hoja_server/deployment.py +28 -0
- hoja_server/email_adapter.py +94 -0
- hoja_server/google_login.py +217 -0
- hoja_server/google_oidc.py +342 -0
- hoja_server/identity_transfer.py +210 -0
- hoja_server/mcp_oauth.py +623 -0
- hoja_server/mcp_tools.py +579 -0
- hoja_server/meeting_policy.py +179 -0
- hoja_server/meetings.py +1332 -0
- hoja_server/meetings_api.py +909 -0
- hoja_server/model_providers.py +205 -0
- hoja_server/realtime.py +690 -0
- hoja_server/resolvers.py +1281 -0
- hoja_server/schema.graphql +477 -0
- hoja_server/schema_sdl.py +8 -0
- hoja_server/secrets_box.py +39 -0
- hoja_server/signup_config.py +292 -0
- hoja_server/signup_gate.py +393 -0
- hoja_server/signup_policy.py +97 -0
- hoja_server/signup_store.py +577 -0
- hoja_server/store.py +2179 -0
- hoja_server/sync.py +249 -0
- hoja_server/tenant_context.py +131 -0
- hoja_server/turnstile.py +81 -0
- 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.
|