atlassian-cli 0.12.0__tar.gz → 0.13.0__tar.gz

{atlassian_cli-0.12.0/src/atlassian_cli.egg-info → atlassian_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atlassian-cli
-Version: 0.12.0
+Version: 0.13.0
 Summary: Fast CLI tools for Atlassian Cloud (Confluence + Jira) — optimized for AI agents
 Author-email: Alex Fishlock <alex.fishlock@catapult.cx>
 License-Expression: MIT
@@ -85,6 +85,12 @@ Get your API token at https://id.atlassian.com/manage-profile/security/api-token
 
 > Legacy `CONFLUENCE_URL` / `CONFLUENCE_EMAIL` / `CONFLUENCE_TOKEN` are also supported.
 
+Organisation admin commands (`org`) use a separate org API key, read from the same config file or env:
+```
+ATLASSIAN_ORG_API_KEY=ATCTT...   # admin.atlassian.com > org > Settings > API keys (personal ATATT tokens get 401)
+ATLASSIAN_ORG_ID=your-org-id     # or pass --org-id
+```
+
 ## Confluence CLI
 
 Manages Confluence pages as local JSON files in ADF (Atlassian Document Format). No markdown — ADF preserves every macro, panel, and table perfectly.
@@ -261,6 +267,18 @@ jira assets delete 123
 jira assets type-create 1 "Network Device" --description "Switches and routers"
 ```
 
+## Organisation admin CLI
+
+Read-only access to the org admin API: audit log, managed users, audit action types.
+
+```bash
+org events --from <epoch ms> --to <epoch ms> [--org-id ID] [--dump FILE]  # org audit log events
+org users [--org-id ID] [--dump FILE]          # managed accounts with last_active
+org event-actions [--org-id ID] [--dump FILE]  # every audit event action type
+```
+
+`--dump` writes `{"total": N, "<key>": [...]}`. Audit retention is about 180 days.
+
 ## `--json` flag
 
 Both CLIs accept a global `--json` flag that switches all output to machine-readable JSON. Perfect for piping into `jq` or parsing from code.
@@ -298,12 +316,14 @@ src/atlassian_cli/
   jira.py         Jira CLI entry point (subparsers)
   jira_issues.py  Jira issue commands (v3 API)
   jira_assets.py  Jira Assets commands (Assets v1 API)
+  org.py          Org admin commands (admin v1 API)
 ```
 
 **APIs used:**
 - Confluence Cloud REST API v2 (`/wiki/api/v2/`)
 - Jira Cloud REST API v3 (`/rest/api/3/`)
 - Jira Assets REST API v1 (`api.atlassian.com/jsm/assets/workspace/{id}/v1`)
+- Organisation admin API v1 (`api.atlassian.com/admin/v1/orgs/{orgId}`)
 
 ## Development
 

{atlassian_cli-0.12.0 → atlassian_cli-0.13.0}/README.md

@@ -54,6 +54,12 @@ Get your API token at https://id.atlassian.com/manage-profile/security/api-token
 
 > Legacy `CONFLUENCE_URL` / `CONFLUENCE_EMAIL` / `CONFLUENCE_TOKEN` are also supported.
 
+Organisation admin commands (`org`) use a separate org API key, read from the same config file or env:
+```
+ATLASSIAN_ORG_API_KEY=ATCTT...   # admin.atlassian.com > org > Settings > API keys (personal ATATT tokens get 401)
+ATLASSIAN_ORG_ID=your-org-id     # or pass --org-id
+```
+
 ## Confluence CLI
 
 Manages Confluence pages as local JSON files in ADF (Atlassian Document Format). No markdown — ADF preserves every macro, panel, and table perfectly.
@@ -230,6 +236,18 @@ jira assets delete 123
 jira assets type-create 1 "Network Device" --description "Switches and routers"
 ```
 
+## Organisation admin CLI
+
+Read-only access to the org admin API: audit log, managed users, audit action types.
+
+```bash
+org events --from <epoch ms> --to <epoch ms> [--org-id ID] [--dump FILE]  # org audit log events
+org users [--org-id ID] [--dump FILE]          # managed accounts with last_active
+org event-actions [--org-id ID] [--dump FILE]  # every audit event action type
+```
+
+`--dump` writes `{"total": N, "<key>": [...]}`. Audit retention is about 180 days.
+
 ## `--json` flag
 
 Both CLIs accept a global `--json` flag that switches all output to machine-readable JSON. Perfect for piping into `jq` or parsing from code.
@@ -267,12 +285,14 @@ src/atlassian_cli/
   jira.py         Jira CLI entry point (subparsers)
   jira_issues.py  Jira issue commands (v3 API)
   jira_assets.py  Jira Assets commands (Assets v1 API)
+  org.py          Org admin commands (admin v1 API)
 ```
 
 **APIs used:**
 - Confluence Cloud REST API v2 (`/wiki/api/v2/`)
 - Jira Cloud REST API v3 (`/rest/api/3/`)
 - Jira Assets REST API v1 (`api.atlassian.com/jsm/assets/workspace/{id}/v1`)
+- Organisation admin API v1 (`api.atlassian.com/admin/v1/orgs/{orgId}`)
 
 ## Development
 

{atlassian_cli-0.12.0 → atlassian_cli-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atlassian-cli"
-version = "0.12.0"
+version = "0.13.0"
 description = "Fast CLI tools for Atlassian Cloud (Confluence + Jira) — optimized for AI agents"
 readme = "README.md"
 license = "MIT"
@@ -45,6 +45,7 @@ Issues = "https://github.com/catapultcx/atlassian-cli/issues"
 [project.scripts]
 confluence = "atlassian_cli.confluence:main"
 jira = "atlassian_cli.jira:main"
+org = "atlassian_cli.org:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{atlassian_cli-0.12.0 → atlassian_cli-0.13.0}/src/atlassian_cli/config.py

@@ -77,3 +77,27 @@ def setup():
     url, email, token = get_config()
     session = get_session(email, token)
     return session, url
+
+
+ORG_API = 'https://api.atlassian.com/admin/v1/orgs'
+
+
+def get_org_config(org_id=None):
+    env = load_env()
+    api_key = env.get('ATLASSIAN_ORG_API_KEY', os.environ.get('ATLASSIAN_ORG_API_KEY'))
+    org_id = org_id or env.get('ATLASSIAN_ORG_ID', os.environ.get('ATLASSIAN_ORG_ID'))
+    if not api_key:
+        sys.stderr.write('ERR Missing ATLASSIAN_ORG_API_KEY (organisation admin API key)\n'
+                         'Set it in .env or as an environment variable.\n')
+        sys.exit(1)
+    if not org_id:
+        sys.stderr.write('ERR Missing ATLASSIAN_ORG_ID: set it in .env or pass --org-id.\n')
+        sys.exit(1)
+    return api_key.strip(), org_id.strip()
+
+
+def org_setup(org_id=None):
+    api_key, org_id = get_org_config(org_id)
+    session = requests.Session()
+    session.headers.update({'Authorization': f'Bearer {api_key}', 'Accept': 'application/json'})
+    return session, f'{ORG_API}/{org_id}'

atlassian_cli-0.13.0/src/atlassian_cli/org.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Atlassian organisation admin CLI: audit log events, managed users, event action types.
+
+Uses the organisation admin API (api.atlassian.com/admin/v1/orgs/{orgId}) with an org API key,
+which is separate from the site credentials the confluence and jira commands use.
+"""
+
+import argparse
+import json
+import sys
+
+from atlassian_cli.config import org_setup
+from atlassian_cli.http import APIError, _retry
+from atlassian_cli.output import emit, emit_error, is_json_mode, set_json_mode
+
+
+def _get(session, url, params=None):
+    response = _retry(session.get, url, params=params)
+    if response.ok:
+        return response.json()
+    raise APIError(response.status_code, response.text)
+
+
+def fetch_events(session, base, start_ms, end_ms):
+    # events-stream drops out of the window if a cursor is sent without from/to.
+    window = {'from': start_ms, 'to': end_ms}
+    params = dict(window)
+    events = []
+    while True:
+        data = _get(session, f'{base}/events-stream', params)
+        batch = data.get('data') or []
+        events.extend(batch)
+        cursor = (data.get('meta') or {}).get('next')
+        if not batch or not cursor:
+            return events
+        params = dict(window, cursor=cursor)
+
+
+def fetch_list(session, url):
+    items = []
+    while url:
+        data = _get(session, url)
+        items.extend(data.get('data') or [])
+        url = (data.get('links') or {}).get('next')
+    return items
+
+
+def _finish(args, key, items, line):
+    if args.dump:
+        with open(args.dump, 'w') as fh:
+            json.dump({'total': len(items), key: items}, fh, indent=2)
+    elif not is_json_mode():
+        for item in items:
+            print(line(item))
+    emit('DONE', f'{len(items)} {key}', data={'total': len(items)})
+
+
+def cmd_events(args):
+    session, base = org_setup(args.org_id)
+    events = fetch_events(session, base, args.start_ms, args.end_ms)
+    _finish(args, 'events', events, lambda e: ' '.join([
+        e['attributes'].get('time', ''), e['attributes'].get('action', ''),
+        (e['attributes'].get('actor') or {}).get('name', '')]))
+
+
+def cmd_users(args):
+    session, base = org_setup(args.org_id)
+    users = fetch_list(session, f'{base}/users')
+    _finish(args, 'users', users,
+            lambda u: f"{u.get('account_id', '')} {u.get('email', '')} {u.get('last_active', '')}")
+
+
+def cmd_event_actions(args):
+    session, base = org_setup(args.org_id)
+    actions = fetch_list(session, f'{base}/event-actions')
+    _finish(args, 'actions', actions, lambda a: a.get('id', ''))
+
+
+def main():
+    from atlassian_cli.update_check import check_for_update
+    check_for_update()
+
+    if '--json' in sys.argv:
+        sys.argv.remove('--json')
+        set_json_mode(True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument('--org-id', help='Organisation id (default: ATLASSIAN_ORG_ID from config)')
+    common.add_argument('--dump', metavar='FILE', help='Save the full data to a JSON file')
+
+    parser = argparse.ArgumentParser(prog='org',
+                                     description='Atlassian organisation admin: audit events, users, event actions')
+    sub = parser.add_subparsers(dest='command', required=True)
+
+    p = sub.add_parser('events', parents=[common], help='Audit log events in a time window')
+    p.add_argument('--from', dest='start_ms', type=int, required=True, help='Window start, epoch milliseconds')
+    p.add_argument('--to', dest='end_ms', type=int, required=True, help='Window end, epoch milliseconds')
+    p.set_defaults(func=cmd_events)
+
+    p = sub.add_parser('users', parents=[common], help='Managed accounts with last-active dates')
+    p.set_defaults(func=cmd_users)
+
+    p = sub.add_parser('event-actions', parents=[common], help='Every audit event action type')
+    p.set_defaults(func=cmd_event_actions)
+
+    args = parser.parse_args()
+    try:
+        args.func(args)
+    except APIError as e:
+        emit_error(str(e))
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == '__main__':
+    main()

{atlassian_cli-0.12.0 → atlassian_cli-0.13.0/src/atlassian_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atlassian-cli
-Version: 0.12.0
+Version: 0.13.0
 Summary: Fast CLI tools for Atlassian Cloud (Confluence + Jira) — optimized for AI agents
 Author-email: Alex Fishlock <alex.fishlock@catapult.cx>
 License-Expression: MIT
@@ -85,6 +85,12 @@ Get your API token at https://id.atlassian.com/manage-profile/security/api-token
 
 > Legacy `CONFLUENCE_URL` / `CONFLUENCE_EMAIL` / `CONFLUENCE_TOKEN` are also supported.
 
+Organisation admin commands (`org`) use a separate org API key, read from the same config file or env:
+```
+ATLASSIAN_ORG_API_KEY=ATCTT...   # admin.atlassian.com > org > Settings > API keys (personal ATATT tokens get 401)
+ATLASSIAN_ORG_ID=your-org-id     # or pass --org-id
+```
+
 ## Confluence CLI
 
 Manages Confluence pages as local JSON files in ADF (Atlassian Document Format). No markdown — ADF preserves every macro, panel, and table perfectly.
@@ -261,6 +267,18 @@ jira assets delete 123
 jira assets type-create 1 "Network Device" --description "Switches and routers"
 ```
 
+## Organisation admin CLI
+
+Read-only access to the org admin API: audit log, managed users, audit action types.
+
+```bash
+org events --from <epoch ms> --to <epoch ms> [--org-id ID] [--dump FILE]  # org audit log events
+org users [--org-id ID] [--dump FILE]          # managed accounts with last_active
+org event-actions [--org-id ID] [--dump FILE]  # every audit event action type
+```
+
+`--dump` writes `{"total": N, "<key>": [...]}`. Audit retention is about 180 days.
+
 ## `--json` flag
 
 Both CLIs accept a global `--json` flag that switches all output to machine-readable JSON. Perfect for piping into `jq` or parsing from code.
@@ -298,12 +316,14 @@ src/atlassian_cli/
   jira.py         Jira CLI entry point (subparsers)
   jira_issues.py  Jira issue commands (v3 API)
   jira_assets.py  Jira Assets commands (Assets v1 API)
+  org.py          Org admin commands (admin v1 API)
 ```
 
 **APIs used:**
 - Confluence Cloud REST API v2 (`/wiki/api/v2/`)
 - Jira Cloud REST API v3 (`/rest/api/3/`)
 - Jira Assets REST API v1 (`api.atlassian.com/jsm/assets/workspace/{id}/v1`)
+- Organisation admin API v1 (`api.atlassian.com/admin/v1/orgs/{orgId}`)
 
 ## Development
 

{atlassian_cli-0.12.0 → atlassian_cli-0.13.0}/src/atlassian_cli.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/atlassian_cli/http.py
 src/atlassian_cli/jira.py
 src/atlassian_cli/jira_assets.py
 src/atlassian_cli/jira_issues.py
+src/atlassian_cli/org.py
 src/atlassian_cli/output.py
 src/atlassian_cli/update_check.py
 src/atlassian_cli.egg-info/PKG-INFO
@@ -24,4 +25,5 @@ tests/test_confluence.py
 tests/test_http.py
 tests/test_jira_assets.py
 tests/test_jira_issues.py
+tests/test_org.py
 tests/test_output.py

{atlassian_cli-0.12.0 → atlassian_cli-0.13.0}/src/atlassian_cli.egg-info/entry_points.txt

@@ -1,3 +1,4 @@
 [console_scripts]
 confluence = atlassian_cli.confluence:main
 jira = atlassian_cli.jira:main
+org = atlassian_cli.org:main

{atlassian_cli-0.12.0 → atlassian_cli-0.13.0}/tests/test_config.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from atlassian_cli.config import get_config, get_session, load_env, setup
+from atlassian_cli.config import get_config, get_org_config, get_session, load_env, org_setup, setup
 
 
 class TestLoadEnv:
@@ -130,3 +130,45 @@ class TestSetup:
         session, base = setup()
         assert base == "https://test.atlassian.net"
         assert session.auth is not None
+
+
+class TestGetOrgConfig:
+    @pytest.fixture(autouse=True)
+    def _isolate(self, monkeypatch, tmp_path):
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+        monkeypatch.delenv("ATLASSIAN_CLI_CONFIG", raising=False)
+        monkeypatch.delenv("ATLASSIAN_ORG_API_KEY", raising=False)
+        monkeypatch.delenv("ATLASSIAN_ORG_ID", raising=False)
+
+    def test_reads_key_and_org_id_from_config(self, tmp_path):
+        (tmp_path / ".env").write_text("ATLASSIAN_ORG_API_KEY=ATCTT-k\nATLASSIAN_ORG_ID=org-1\n")
+        assert get_org_config() == ("ATCTT-k", "org-1")
+
+    def test_explicit_org_id_wins(self, tmp_path):
+        (tmp_path / ".env").write_text("ATLASSIAN_ORG_API_KEY=ATCTT-k\nATLASSIAN_ORG_ID=org-1\n")
+        assert get_org_config("org-2") == ("ATCTT-k", "org-2")
+
+    def test_env_var_fallback(self, monkeypatch):
+        monkeypatch.setenv("ATLASSIAN_ORG_API_KEY", "ATCTT-e")
+        monkeypatch.setenv("ATLASSIAN_ORG_ID", "org-e")
+        assert get_org_config() == ("ATCTT-e", "org-e")
+
+    def test_missing_key_exits_naming_it(self, capsys):
+        with pytest.raises(SystemExit):
+            get_org_config("org-1")
+        assert "ATLASSIAN_ORG_API_KEY" in capsys.readouterr().err
+
+    def test_missing_org_id_exits_naming_it(self, tmp_path, capsys):
+        (tmp_path / ".env").write_text("ATLASSIAN_ORG_API_KEY=ATCTT-k\n")
+        with pytest.raises(SystemExit):
+            get_org_config()
+        assert "ATLASSIAN_ORG_ID" in capsys.readouterr().err
+
+    def test_org_setup_uses_bearer_auth(self, tmp_path):
+        (tmp_path / ".env").write_text("ATLASSIAN_ORG_API_KEY=ATCTT-k\n")
+        session, base = org_setup("org-1")
+        assert session.headers["Authorization"] == "Bearer ATCTT-k"
+        assert session.auth is None
+        assert base == "https://api.atlassian.com/admin/v1/orgs/org-1"

atlassian_cli-0.13.0/tests/test_org.py

@@ -0,0 +1,95 @@
+"""Tests for atlassian_cli.org."""
+
+import json
+from argparse import Namespace
+from urllib.parse import parse_qsl, urlparse
+
+import pytest
+
+from atlassian_cli import org
+from atlassian_cli.http import APIError
+from atlassian_cli.output import set_json_mode
+
+ORG_BASE = "https://api.atlassian.com/admin/v1/orgs/org-1"
+EVENTS = f"{ORG_BASE}/events-stream"
+
+
+@pytest.fixture(autouse=True)
+def _patch_setup(monkeypatch, mock_session):
+    monkeypatch.setattr("atlassian_cli.org.org_setup", lambda org_id=None: (mock_session, ORG_BASE))
+    set_json_mode(False)
+
+
+@pytest.fixture
+def slept(monkeypatch):
+    calls = []
+    monkeypatch.setattr("atlassian_cli.http.time.sleep", calls.append)
+    return calls
+
+
+def _params(call):
+    return dict(parse_qsl(urlparse(call.request.url).query))
+
+
+class TestFetchEvents:
+    def test_pages_by_cursor_keeping_the_window(self, mock_session, mocked_responses):
+        mocked_responses.get(EVENTS, json={"data": [{"id": "1"}, {"id": "2"}], "meta": {"next": "c1"}})
+        mocked_responses.get(EVENTS, json={"data": [{"id": "3"}], "meta": {"next": "c2"}})
+        mocked_responses.get(EVENTS, json={"data": [], "meta": {}})
+        events = org.fetch_events(mock_session, ORG_BASE, 1000, 2000)
+        assert [e["id"] for e in events] == ["1", "2", "3"]
+        params = [_params(c) for c in mocked_responses.calls]
+        assert all(p["from"] == "1000" and p["to"] == "2000" for p in params)
+        assert [p.get("cursor") for p in params] == [None, "c1", "c2"]
+
+    def test_retries_429_with_the_same_request(self, mock_session, mocked_responses, slept):
+        mocked_responses.get(EVENTS, json={"data": [{"id": "1"}], "meta": {"next": "c1"}})
+        mocked_responses.get(EVENTS, status=429, headers={"Retry-After": "3"})
+        mocked_responses.get(EVENTS, json={"data": [{"id": "2"}], "meta": {}})
+        events = org.fetch_events(mock_session, ORG_BASE, 1000, 2000)
+        assert [e["id"] for e in events] == ["1", "2"]
+        params = [_params(c) for c in mocked_responses.calls]
+        assert [p.get("cursor") for p in params] == [None, "c1", "c1"]
+        assert all(p["from"] == "1000" and p["to"] == "2000" for p in params)
+        assert len(slept) == 1 and 2.1 <= slept[0] <= 3.9
+
+    def test_http_error_raises(self, mock_session, mocked_responses):
+        mocked_responses.get(EVENTS, status=401, body="unauthorised")
+        with pytest.raises(APIError):
+            org.fetch_events(mock_session, ORG_BASE, 1000, 2000)
+
+
+class TestFetchList:
+    def test_follows_absolute_next_links(self, mock_session, mocked_responses):
+        mocked_responses.get(f"{ORG_BASE}/users", json={"data": [{"account_id": "a"}], "links": {"next": "https://n.example/p2"}})
+        mocked_responses.get("https://n.example/p2", json={"data": [{"account_id": "b"}], "links": {}})
+        assert [u["account_id"] for u in org.fetch_list(mock_session, f"{ORG_BASE}/users")] == ["a", "b"]
+
+
+class TestCommands:
+    def test_events_writes_the_dump(self, mocked_responses, tmp_path):
+        mocked_responses.get(EVENTS, json={"data": [{"id": "1"}], "meta": {}})
+        dump = tmp_path / "events.json"
+        org.cmd_events(Namespace(org_id="org-1", start_ms=1000, end_ms=2000, dump=str(dump)))
+        assert json.loads(dump.read_text()) == {"total": 1, "events": [{"id": "1"}]}
+
+    def test_users_writes_the_dump(self, mocked_responses, tmp_path):
+        mocked_responses.get(f"{ORG_BASE}/users", json={"data": [{"account_id": "a", "last_active": "x"}], "links": {}})
+        dump = tmp_path / "users.json"
+        org.cmd_users(Namespace(org_id=None, dump=str(dump)))
+        assert json.loads(dump.read_text())["users"] == [{"account_id": "a", "last_active": "x"}]
+
+    def test_event_actions_writes_the_dump(self, mocked_responses, tmp_path):
+        mocked_responses.get(f"{ORG_BASE}/event-actions", json={"data": [{"id": "x"}], "links": {}})
+        dump = tmp_path / "actions.json"
+        org.cmd_event_actions(Namespace(org_id=None, dump=str(dump)))
+        assert json.loads(dump.read_text())["actions"] == [{"id": "x"}]
+
+    def test_main_parses_the_window_and_org_id(self, monkeypatch):
+        seen = []
+        monkeypatch.setattr("atlassian_cli.update_check.check_for_update", lambda: None)
+        monkeypatch.setattr("atlassian_cli.org.cmd_events", seen.append)
+        monkeypatch.setattr("sys.argv", ["org", "events", "--from", "1", "--to", "2",
+                                         "--org-id", "org-9", "--dump", "f.json", "--json"])
+        org.main()
+        assert (seen[0].start_ms, seen[0].end_ms, seen[0].org_id, seen[0].dump) == (1, 2, "org-9", "f.json")