atli 0.5.1__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.
@@ -0,0 +1,96 @@
1
+ ---
2
+ name: using-atli
3
+ description: Use when the task touches self-hosted Jira issues or Confluence pages — creating tickets, transitioning status, publishing design docs, searching tickets or pages. Routes to atli-jira and atli-confluence for command-level detail.
4
+ ---
5
+
6
+ # Using atli
7
+
8
+ `atli` is a lightweight CLI that talks to **self-hosted** Jira and Confluence (Server / Data Center) over their REST APIs. Always prefer it over generating raw `curl` commands or asking the user to click through the web UI.
9
+
10
+ ## When this skill applies
11
+
12
+ Trigger on any of these intents:
13
+
14
+ - "Create a Jira ticket / issue / story / bug for ..."
15
+ - "What's the status of PROJ-123?" / "Show me PROJ-123"
16
+ - "List all open issues in project PROJ" / "What's assigned to me?"
17
+ - "Edit / assign / link / clone PROJ-123"
18
+ - "Move PROJ-123 to Done / In Progress / Code Review"
19
+ - "Comment on PROJ-123 with ..." / "Log work on PROJ-123"
20
+ - "List epics / sprints / boards in project PROJ"
21
+ - "Publish this doc to Confluence" / "Update the design page"
22
+ - "Find the page about X" / "Search Confluence for ..."
23
+
24
+ Do NOT use this skill for Atlassian **Cloud** (`*.atlassian.net`) instances — `atli` is built for Server / DC with Personal Access Token (PAT) auth. If the host is `*.atlassian.net`, tell the user this CLI is wrong for them.
25
+
26
+ ## Step 1 — verify atli is reachable
27
+
28
+ Before any other command, run:
29
+
30
+ ```bash
31
+ atli config show
32
+ ```
33
+
34
+ To locate the config file, run `atli config path`.
35
+
36
+ Read the output:
37
+
38
+ - If `jira_url` / `confluence_url` show `(unset)` and the task needs that product, **stop and tell the user**:
39
+ > "atli isn't configured for Jira yet. Run `atli config init`, edit the file, or export `ATLI_JIRA_URL` + `ATLI_JIRA_TOKEN`."
40
+ - If the values are present (sources `(file)` or `(env)`), proceed.
41
+
42
+ If the user has multiple instances, they can switch with `--profile <name>` (e.g. `atli --profile staging jira view PROJ-1`).
43
+
44
+ ## Step 2 — pick the right sub-skill
45
+
46
+ | Need | Sub-skill |
47
+ |------|-----------|
48
+ | Create / view / edit / assign / link / list / search / comment / transition / epic / sprint / clone / worklog issues | **atli-jira** |
49
+ | Create / view / update / list / search pages | **atli-confluence** |
50
+
51
+ Both can be combined in one task — e.g. brainstorming → ticket + design doc.
52
+
53
+ ## Step 3 — output mode
54
+
55
+ `atli` has a global `--json` flag that emits machine-readable JSON to stdout. Use it whenever you'll parse the result:
56
+
57
+ ```bash
58
+ KEY=$(atli --json jira create --project PROJ --title "x" --type Task | jq -r .key)
59
+ atli --json jira view "$KEY" | jq -r '.fields.status.name'
60
+ ```
61
+
62
+ For display-only output (showing the user what happened), the default human-readable format is fine.
63
+
64
+ Use `--quiet` to suppress progress messages (e.g. markdown conversion info). Useful in scripts where you only want the final output.
65
+
66
+ ## Step 4 — error handling
67
+
68
+ `atli` exits with status `1` and prints `error: <message>` on failures. The most common ones:
69
+
70
+ - **`Jira not configured` / `Confluence not configured`** → see Step 1.
71
+ - **`HTTP 401`** → token expired or wrong; ask user to refresh PAT.
72
+ - **`HTTP 404` for an issue / page** → confirm key/title with the user.
73
+ - **`no transition 'Done' available` (Jira)** → the workflow doesn't expose that target from the current state. List available with `atli --json jira view KEY` and then call `transition` with one of the names that's actually allowed.
74
+
75
+ ## Global constraints for all atli operations
76
+
77
+ 1. **When an operation is unsupported, explain why and provide evidence**
78
+ - If `atli` does not support an operation (e.g. bulk edits, Confluence page moves, space creation, Jira Cloud), **clearly tell the user the operation cannot be done via `atli`**, explain the specific reason (command does not exist, API unsupported, outside CLI scope), and provide evidence (e.g. `atli --help` output, `atli jira --help` subcommand list, or Atlassian REST API docs reference). Issue linking, attachments (`conf upload`/`attach`), epics/sprints, and worklogs **are** supported — see **atli-jira** / **atli-confluence**.
79
+ - **Do not** make unilateral decisions to bypass `atli` with alternatives (e.g. direct `curl`, web UI actions, script workarounds). You may **suggest** alternatives, but must get user confirmation before executing.
80
+
81
+ 2. **Ask for confirmation when instructions are ambiguous**
82
+ - When parameters are missing or the intent is unclear, **stop and ask the user** rather than inferring intent or choosing defaults.
83
+ - Example: when asked to "link Jira issue XXX to YYY" without specifying the link type (blocks / is blocked by / relates to / duplicates), **first query the instance for supported link types** (`atli --json jira view XXX` or reference the Jira config), list the available options, and ask the user to confirm which link type to use before proceeding.
84
+
85
+ 3. **Confirm before destructive operations**
86
+ - For any `atli` CLI operation that modifies or deletes data (e.g. `atli conf update`, `atli conf delete`, `atli jira edit`/`assign`/`transition`/`comment`/`delete`/`sprint close`), before executing:
87
+ 1. **Show the user the operation details** (target object, change content, impact scope, etc.).
88
+ 2. **Get explicit user approval** before proceeding.
89
+ - For delete/close operations (`atli conf delete`, `atli jira delete`, `atli jira sprint close`), do not use `--yes` to skip confirmation unless the user has explicitly authorized it.
90
+
91
+ ## Anti-patterns
92
+
93
+ - ❌ Generating a `curl` command that hits the Atlassian REST API directly. Use `atli` so auth, retry, and error handling are uniform.
94
+ - ❌ Hard-coding tokens into shell scripts. Use config file / env vars.
95
+ - ❌ Calling `atli jira transition` without first checking which transitions are actually available. The workflow will reject names that aren't reachable from the current state.
96
+ - ❌ Sending markdown to `atli conf create` without `--format markdown` or `--format markdown-macro`. The default `--format storage` treats the body as already-XHTML, so the page renders raw markdown source. The CLI does emit a soft warning when the file ends in `.md` and `--format` is the default, but read the warning — don't ignore it. Pick `markdown` (CLI converts to native Confluence elements) or `markdown-macro` (wiki's Markdown plugin renders, supports Mermaid) based on the wiki's setup.
@@ -0,0 +1,144 @@
1
+ """`atli skills ...` click commands — install the bundled Claude Code skills.
2
+
3
+ The three skills under the repo's `skills/` directory ship inside the wheel as
4
+ package data (`atli/skills/`), so an `atli` installed from a release asset can
5
+ put them on disk without a git checkout. `install.sh` drives the same code path
6
+ when the CLI is available.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ import shutil
13
+ from importlib import resources
14
+ from pathlib import Path
15
+
16
+ import click
17
+
18
+ from atli.output import emit_json, emit_table, fail
19
+
20
+ SKILLS_DIR_ENV = "ATLI_SKILLS_DIR"
21
+ SKILL_MANIFEST = "SKILL.md"
22
+
23
+
24
+ @click.group("skills")
25
+ def skills_cmd() -> None:
26
+ """Inspect and install the bundled agent skills."""
27
+
28
+
29
+ def default_skills_dir() -> Path:
30
+ """Where skills go: $ATLI_SKILLS_DIR, else ~/.agents/skills."""
31
+ override = os.environ.get(SKILLS_DIR_ENV)
32
+ if override:
33
+ return Path(override).expanduser()
34
+ return Path.home() / ".agents" / "skills"
35
+
36
+
37
+ def bundled_skills_root() -> Path:
38
+ """Locate the skills bundled with this installation.
39
+
40
+ They ship as package data (`atli/skills/`), so this resolves the same way
41
+ for wheel installs, sdists and editable checkouts — no source-tree
42
+ fallback needed.
43
+ """
44
+ packaged = Path(str(resources.files("atli"))) / "skills"
45
+ if not packaged.is_dir():
46
+ fail(
47
+ f"bundled skills missing from {packaged}. "
48
+ "Reinstall atli (the wheel should contain atli/skills/)."
49
+ )
50
+ raise AssertionError("unreachable") # pragma: no cover - fail() exits
51
+ return packaged
52
+
53
+
54
+ def _skill_dirs(root: Path) -> list[Path]:
55
+ """Immediate subdirectories of `root` that look like a skill."""
56
+ if not root.is_dir():
57
+ return []
58
+ return sorted(
59
+ p for p in root.iterdir() if p.is_dir() and (p / SKILL_MANIFEST).is_file()
60
+ )
61
+
62
+
63
+ @skills_cmd.command("list")
64
+ @click.pass_context
65
+ def list_cmd(ctx: click.Context) -> None:
66
+ """List the bundled skills and whether they are already installed."""
67
+ root = bundled_skills_root()
68
+ target_root = default_skills_dir()
69
+ rows = [
70
+ {
71
+ "name": src.name,
72
+ "bundled_at": str(src),
73
+ "installed_at": str(target_root / src.name),
74
+ "installed": (target_root / src.name / SKILL_MANIFEST).is_file(),
75
+ }
76
+ for src in _skill_dirs(root)
77
+ ]
78
+ if ctx.obj["json"]:
79
+ emit_json({"source": str(root), "target": str(target_root), "skills": rows})
80
+ return
81
+ emit_table(
82
+ ["Skill", "Installed", "Path"],
83
+ [[r["name"], "yes" if r["installed"] else "no", r["installed_at"]] for r in rows],
84
+ json_mode=False,
85
+ )
86
+
87
+
88
+ @skills_cmd.command("install")
89
+ @click.option(
90
+ "--target",
91
+ "target_dir",
92
+ default=None,
93
+ help=f"Directory to copy skills into (default: ${SKILLS_DIR_ENV} or ~/.agents/skills)",
94
+ )
95
+ @click.option("--dry-run", is_flag=True, help="Report what would be written, change nothing")
96
+ @click.pass_context
97
+ def install_cmd(ctx: click.Context, target_dir: str | None, dry_run: bool) -> None:
98
+ """Copy the bundled skills into the skills directory (overwrites existing)."""
99
+ root = bundled_skills_root()
100
+ dest_root = Path(target_dir).expanduser() if target_dir else default_skills_dir()
101
+ skills = _skill_dirs(root)
102
+ if not skills:
103
+ fail(f"no skills found under {root}")
104
+
105
+ results: list[dict[str, object]] = []
106
+ for src in skills:
107
+ dest = dest_root / src.name
108
+ # `exists()` follows symlinks, so a dangling symlink needs is_symlink()
109
+ # too — otherwise it gets reported as a fresh install rather than a
110
+ # replacement.
111
+ replaced = dest.exists() or dest.is_symlink()
112
+ status = "would replace" if dry_run and replaced else "would install"
113
+ if not dry_run:
114
+ try:
115
+ dest_root.mkdir(parents=True, exist_ok=True)
116
+ # A symlink or plain file at the destination must be unlinked,
117
+ # not rmtree'd: `rm -rf` (what install.sh used to do) removes
118
+ # symlinks, while shutil.rmtree refuses them.
119
+ if dest.is_symlink() or dest.is_file():
120
+ dest.unlink()
121
+ elif replaced:
122
+ shutil.rmtree(dest)
123
+ shutil.copytree(src, dest)
124
+ except OSError as e:
125
+ fail(f"could not install {src.name} to {dest}: {e}")
126
+ status = "replaced" if replaced else "installed"
127
+ results.append({"name": src.name, "path": str(dest), "status": status})
128
+
129
+ if ctx.obj["json"]:
130
+ emit_json(
131
+ {
132
+ "source": str(root),
133
+ "target": str(dest_root),
134
+ "dry_run": dry_run,
135
+ "skills": results,
136
+ "count": len(results),
137
+ }
138
+ )
139
+ return
140
+ emit_table(
141
+ ["Skill", "Status", "Path"],
142
+ [[str(r["name"]), str(r["status"]), str(r["path"])] for r in results],
143
+ json_mode=False,
144
+ )
@@ -0,0 +1,91 @@
1
+ Metadata-Version: 2.5
2
+ Name: atli
3
+ Version: 0.5.1
4
+ Summary: Lightweight CLI for self-hosted Jira and Confluence (Server / Data Center)
5
+ Project-URL: Homepage, https://github.com/yuanyuan06/atli-kit
6
+ Project-URL: Repository, https://github.com/yuanyuan06/atli-kit
7
+ Project-URL: Issues, https://github.com/yuanyuan06/atli-kit/issues
8
+ Project-URL: Documentation, https://github.com/yuanyuan06/atli-kit/blob/main/docs/user-guide.md
9
+ Project-URL: Changelog, https://github.com/yuanyuan06/atli-kit/blob/main/docs/CHANGELOG.md
10
+ Author: atli contributors
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: atlassian,cli,confluence,data-center,jira,server
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Software Development :: Bug Tracking
25
+ Classifier: Topic :: Utilities
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: click>=8.1
28
+ Requires-Dist: httpx>=0.27
29
+ Requires-Dist: markdown-it-py>=3.0
30
+ Requires-Dist: pydantic>=2.0
31
+ Requires-Dist: rich>=13.0
32
+ Requires-Dist: tomli>=2.0.0; python_version < '3.11'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # atli
36
+
37
+ Lightweight CLI for self-hosted **Jira** and **Confluence** (Server / Data Center).
38
+
39
+ No Atlassian SDK — talks directly to the REST APIs over `httpx`. Bearer-token
40
+ (PAT) auth, REST API v2, plain `click` commands, `--json` on everything for
41
+ scripting.
42
+
43
+ > **This package targets Server / Data Center only.** Anything `*.atlassian.net`
44
+ > (Cloud) is out of scope.
45
+
46
+ ## Install
47
+
48
+ ```bash
49
+ uv tool install atli # or: pipx install atli
50
+ atli skills install # optional: the 3 bundled agent skills → ~/.agents/skills
51
+ ```
52
+
53
+ ## Quick start
54
+
55
+ ```bash
56
+ atli config init # writes ~/.config/atli/config.toml (chmod 600)
57
+ $EDITOR ~/.config/atli/config.toml # fill in URLs + personal access tokens
58
+ atli config validate # check connectivity and credentials
59
+
60
+ atli jira view PROJ-123
61
+ atli jira list --jql "assignee = currentUser() AND status != Done"
62
+ atli jira create --project PROJ --type Task --summary "Fix the thing"
63
+ atli jira transition PROJ-123 --to "In Progress"
64
+
65
+ atli conf view --space TEAM --title "Design Doc"
66
+ atli conf create --space TEAM --title "Notes" --file notes.md --format markdown
67
+ ```
68
+
69
+ Config comes from `~/.config/atli/config.toml`, or from env vars
70
+ `ATLI_JIRA_URL` / `ATLI_JIRA_TOKEN` / `ATLI_CONFLUENCE_URL` /
71
+ `ATLI_CONFLUENCE_TOKEN` (env wins over file). `--profile NAME` picks a
72
+ `[profile]` section.
73
+
74
+ ## Agent skills
75
+
76
+ The wheel bundles three Claude Code skills (`using-atli`, `atli-jira`,
77
+ `atli-confluence`). They are package data, not installed automatically:
78
+
79
+ ```bash
80
+ atli skills list # bundled vs installed
81
+ atli skills install # → ~/.agents/skills (or $ATLI_SKILLS_DIR)
82
+ atli skills install --target ~/.claude/skills
83
+ ```
84
+
85
+ ## Links
86
+
87
+ - Documentation: <https://github.com/yuanyuan06/atli-kit/blob/main/docs/user-guide.md>
88
+ - Upgrade notes: <https://github.com/yuanyuan06/atli-kit/blob/main/docs/UPGRADE.md>
89
+ - Changelog: <https://github.com/yuanyuan06/atli-kit/blob/main/docs/CHANGELOG.md>
90
+
91
+ MIT licensed.
@@ -0,0 +1,29 @@
1
+ atli/__init__.py,sha256=ooctMnwc29a83MxzKl1tD_gWAHpUs6AbZPys15MT6hA,91
2
+ atli/__main__.py,sha256=jPNlhK68VKlc3ehdnC2xJ4nmsIMFAUBXgdmx8TLW88w,112
3
+ atli/cli.py,sha256=0Q7q5i9JWlSnsUn4rQYvNZFF7Cly4cX-IwVpOAbLPG0,2146
4
+ atli/client.py,sha256=zT5j7fBMb__QmpQuMahCMnKe2sTIKLKxi1YtVsBx_Bs,5590
5
+ atli/commands_util.py,sha256=8AgjeH0b_IXkIUooXi8tSFFGHkY6F-xEJk5KNt6QzTQ,1458
6
+ atli/config.py,sha256=RJH4xTp-5iQIWh3VXJfqPUCJX3zXcHBopX_DyORLt2o,3611
7
+ atli/config_commands.py,sha256=kpg2bryI2WS93NDJzbUEPmTEPZDNFczuuBVOzr8gH-g,8189
8
+ atli/output.py,sha256=YqkkI5AU5CnNL1me7scmUaYbVBLofyIVssGKJdn0iAc,1683
9
+ atli/skills_commands.py,sha256=NsrSs0yWb_-UKhgXdfeixgDvC5OjswUKl0UQXaWuUOM,4982
10
+ atli/confluence/__init__.py,sha256=-Tx2v8X87HZUXko5MrjucUWzwDurdmZHLrYLjte5m30,51
11
+ atli/confluence/client.py,sha256=CoAJukO3SWgCwgNCBkUOUJpd3Jabg3ScRb78Xb2qPHE,16146
12
+ atli/confluence/commands.py,sha256=y4sXeuVkZ3uVeq9_4ibk1nyuSbp9xp9Vm-BJIogyLVk,36215
13
+ atli/confluence/markdown.py,sha256=DZShCE2G-3c3lmfhxNVWY6EllTjJ114KPeyMI6RsQwg,6554
14
+ atli/jira/__init__.py,sha256=xBC-bTsdZ8NLaPDjO-n5gHYfpb0-_5aZmcoapMrFi-k,45
15
+ atli/jira/agile.py,sha256=rGdcSps-krmbC3n_VGA8NxvhjUYDaB_WxZ0I_lrLUJ0,9887
16
+ atli/jira/agile_commands.py,sha256=s5w0Lnt2JBwcZbaQiXOhd0LL54hiS-Q1pN8ZvuBjmuM,14328
17
+ atli/jira/body.py,sha256=rAdl4MGH2EeBaqFiuRSCbawDFk6LehbzMt5sNBa7kng,1149
18
+ atli/jira/client.py,sha256=LROdVK9xFr0W2F-IxNxeavGP6JaVIf9kMCiKp7blk-s,19184
19
+ atli/jira/commands.py,sha256=nUHj4SxsUgx-h8rbU1wUq-Dlcndvn6EEipYTaODzv6M,47627
20
+ atli/jira/fields.py,sha256=SFl1LVxnrwtTucmeQCFtLrarDP5tPhmLhjF0IP5NSnA,2493
21
+ atli/jira/jql.py,sha256=LJ9m3aRMhQp-8_2G6Jpgs8gdZmJjgmmBoA_TJTWeGio,2354
22
+ atli/skills/atli-confluence/SKILL.md,sha256=0AF1x6uU09YEz7xpEwizBjbQkSk4NX4jd-ENyqMqbq8,9740
23
+ atli/skills/atli-jira/SKILL.md,sha256=TMd3fgDIWPv2AYRz0h8C8IFHQ-ZTbz9q3SR6xJyGYO4,10350
24
+ atli/skills/using-atli/SKILL.md,sha256=JdfrNI-oXv2rgfpVackdMvumd-SBTcYfCj8SBXF8SJ0,6334
25
+ atli-0.5.1.dist-info/METADATA,sha256=I7QR4I218R98gQUdibFc0NKgt77iXCIMjf3HHOrZ8Hc,3451
26
+ atli-0.5.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
27
+ atli-0.5.1.dist-info/entry_points.txt,sha256=pZuLr4qPZYgB__1EHl3GeNe1CqhRsRb7jTrPx0yXKQk,39
28
+ atli-0.5.1.dist-info/licenses/LICENSE,sha256=RCbJxdTlRVlBsVqVE1faG9wynOzJW6A283GnUVR3me4,1074
29
+ atli-0.5.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ atli = atli.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 atli contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.