sudodocs-cli 1.0.0__tar.gz

sudodocs_cli-1.0.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: sudodocs-cli
+Version: 1.0.0
+Summary: Command-line interface and Headless API client for SudoDocs
+Author: SudoDocs
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://sudodocs.com
+Project-URL: Documentation, https://docs.sudodocs.com/docs/cli-guide
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.7
+Requires-Dist: requests>=2.31.0
+Requires-Dist: PyYAML>=6.0.1
+
+# sudodocs-cli
+
+Command-line interface and Headless API client for [SudoDocs](https://sudodocs.com) - automated documentation for technical teams. Trigger repository syncs, convert specs to docs, manage your Knowledge Base, and administer users, integrations, and settings from a terminal or CI/CD pipeline instead of the dashboard.
+
+**Requires a SudoDocs Enterprise plan.** The CLI is an Enterprise-only feature - every command authenticates against your organization's SudoDocs account and fails with an upgrade message on other plans.
+
+## Install
+
+```bash
+pip install sudodocs-cli
+```
+
+## Quick Start
+
+```bash
+sudodocs login              # opens your browser to approve a device login
+sudodocs whoami              # confirm who you're logged in as
+sudodocs sync --integration-id 42
+```
+
+See the full [CLI Tasks documentation](https://docs.sudodocs.com/docs/cli-guide) for every available command, one page per SudoDocs feature it automates.
+
+## License
+
+Proprietary - use of this tool is governed by the [SudoDocs Terms of Service](https://sudodocs.com). Source is provided for transparency and issue reporting, not for redistribution or reuse outside SudoDocs.

sudodocs_cli-1.0.0/README.md

@@ -0,0 +1,25 @@
+# sudodocs-cli
+
+Command-line interface and Headless API client for [SudoDocs](https://sudodocs.com) - automated documentation for technical teams. Trigger repository syncs, convert specs to docs, manage your Knowledge Base, and administer users, integrations, and settings from a terminal or CI/CD pipeline instead of the dashboard.
+
+**Requires a SudoDocs Enterprise plan.** The CLI is an Enterprise-only feature - every command authenticates against your organization's SudoDocs account and fails with an upgrade message on other plans.
+
+## Install
+
+```bash
+pip install sudodocs-cli
+```
+
+## Quick Start
+
+```bash
+sudodocs login              # opens your browser to approve a device login
+sudodocs whoami              # confirm who you're logged in as
+sudodocs sync --integration-id 42
+```
+
+See the full [CLI Tasks documentation](https://docs.sudodocs.com/docs/cli-guide) for every available command, one page per SudoDocs feature it automates.
+
+## License
+
+Proprietary - use of this tool is governed by the [SudoDocs Terms of Service](https://sudodocs.com). Source is provided for transparency and issue reporting, not for redistribution or reuse outside SudoDocs.

sudodocs_cli-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sudodocs-cli"
+version = "1.0.0"
+description = "Command-line interface and Headless API client for SudoDocs"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "LicenseRef-Proprietary"
+authors = [{name = "SudoDocs"}]
+dependencies = [
+    "click>=8.1.7",
+    "requests>=2.31.0",
+    "PyYAML>=6.0.1",
+]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://sudodocs.com"
+Documentation = "https://docs.sudodocs.com/docs/cli-guide"
+
+[project.scripts]
+sudodocs = "sudodocs_cli.main:cli"
+
+[tool.setuptools.packages.find]
+include = ["sudodocs_cli*"]

sudodocs_cli-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sudodocs_cli-1.0.0/sudodocs_cli/main.py

@@ -0,0 +1,742 @@
+import click
+import requests
+import time
+import yaml
+import json
+import os
+import sys
+import webbrowser
+
+DEFAULT_BASE_URL = 'https://api.sudodocs.com'
+
+def _credentials_path():
+    return os.path.join(os.path.expanduser('~'), '.sudodocs', 'credentials.json')
+
+def _load_credentials():
+    path = _credentials_path()
+    if not os.path.exists(path):
+        return {}
+    try:
+        with open(path, 'r') as f:
+            return json.load(f) or {}
+    except (ValueError, OSError):
+        return {}
+
+def _save_credentials(api_key, base_url):
+    path = _credentials_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, 'w') as f:
+        json.dump({"api_key": api_key, "base_url": base_url}, f)
+    os.chmod(path, 0o600)
+
+def _repo_config():
+    config_path = os.path.join(os.getcwd(), 'sudodocs.yaml')
+    return (yaml.safe_load(open(config_path)) or {}) if os.path.exists(config_path) else {}
+
+def resolve_base_url():
+    """Base URL resolution shared by every command, including `login` (which
+    runs before any api_key exists, so it can't go through load_config())."""
+    return os.getenv('SUDODOCS_BASE_URL') or _repo_config().get('base_url') or _load_credentials().get('base_url') or DEFAULT_BASE_URL
+
+def load_config():
+    config = _repo_config()
+    creds = _load_credentials()
+    api_key = os.getenv('SUDODOCS_API_KEY') or config.get('api_key') or creds.get('api_key')
+    base_url = resolve_base_url()
+    if not api_key:
+        click.secho("Error: Not logged in. Run `sudodocs login`, or set SUDODOCS_API_KEY / add api_key to sudodocs.yaml.", fg="red")
+        sys.exit(1)
+    return api_key, base_url
+
+def api_request(method, path, api_key, base_url, require_job_id=True, **kwargs):
+    """Wraps requests.request and turns non-2xx / unreadable responses into a clean CLI error
+    instead of letting callers crash on a missing 'job_id' key (e.g. bad key, 400, 5xx)."""
+    url = f"{base_url}{path}"
+    try:
+        res = requests.request(method, url, headers={"Authorization": f"Bearer {api_key}"}, **kwargs)
+    except requests.exceptions.RequestException as e:
+        click.secho(f"Error: Could not reach {base_url} ({e})", fg="red")
+        sys.exit(1)
+
+    try:
+        body = res.json()
+    except ValueError:
+        body = {}
+
+    if not res.ok:
+        message = body.get('message') or body.get('error') or res.text or f"HTTP {res.status_code}"
+        click.secho(f"Error: {message}", fg="red")
+        sys.exit(1)
+
+    if require_job_id and 'job_id' not in body:
+        click.secho(f"Error: Unexpected response from server: {body}", fg="red")
+        sys.exit(1)
+
+    return body
+
+def poll_job(job_id, api_key, base_url, timeout=600):
+    url = f"{base_url}/api/v1/jobs/{job_id}"
+    click.echo(f"Waiting for SudoDocs worker (Job: {job_id})", nl=False)
+    start = time.time()
+    while time.time() - start < timeout:
+        try:
+            res = requests.get(url, headers={"Authorization": f"Bearer {api_key}"})
+            body = res.json()
+            if not res.ok:
+                message = body.get('message') or body.get('error') or f"HTTP {res.status_code}"
+                click.secho(f"\nError: {message}", fg="red")
+                sys.exit(1)
+            data = body.get('data', {})
+            if data.get('status') == 'completed':
+                click.secho("\nSuccess!", fg="green")
+                return data.get('result', {})
+            elif data.get('status') == 'failed':
+                click.secho(f"\nFailed: {data.get('error')}", fg="red")
+                sys.exit(1)
+            click.echo(".", nl=False)
+            time.sleep(4)
+        except Exception as e:
+            click.secho(f"\nPolling Error: {e}", fg="red"); sys.exit(1)
+    click.secho("\nTimeout.", fg="red"); sys.exit(1)
+
+@click.group()
+def cli():
+    """SudoDocs CLI: Automate Docs & Validations."""
+    pass
+
+@cli.command()
+@click.option('--integration-id', required=True, type=int)
+def sync(integration_id):
+    """Force vector DB sync for a repo."""
+    api_key, url = load_config()
+    body = api_request('POST', '/api/v1/sync', api_key, url, json={"integration_id": integration_id})
+    poll_job(body['job_id'], api_key, url, 10800)
+
+# Maps a documentation tool to the native syntax SudoDocs should generate.
+# Docusaurus consumes Markdown/MDX, Sphinx consumes reStructuredText.
+TARGET_FORMATS = {'docusaurus': 'md', 'sphinx': 'rst', 'md': 'md', 'rst': 'rst', 'adoc': 'adoc'}
+FORMAT_EXTENSIONS = {'md': '.md', 'rst': '.rst', 'adoc': '.adoc'}
+
+@cli.command()
+@click.argument('file_path', type=click.Path(exists=True))
+@click.option('--type', '-t', 'source_type', type=click.Choice(['openapi', 'helm']), required=True)
+@click.option('--target', 'target', type=click.Choice(sorted(TARGET_FORMATS)), default='docusaurus',
+              help="Documentation tool (or raw format) to generate output for.")
+@click.option('--output', '-o', 'output_path', type=click.Path(), default=None,
+              help="Local file to write the generated docs to (e.g. docs/api-reference.md for Docusaurus, or docs/api-reference.rst for Sphinx). Defaults to the input filename with the target's extension.")
+def convert(file_path, source_type, target, output_path):
+    """Convert an OpenAPI/Helm spec into Docusaurus (Markdown) or Sphinx (reStructuredText) docs."""
+    api_key, url = load_config()
+    target_format = TARGET_FORMATS[target]
+    with open(file_path, 'r', encoding='utf-8') as f: content = f.read()
+    payload = {"title": os.path.basename(file_path), "source_type": source_type, "content": content, "target_format": target_format}
+    body = api_request('POST', '/api/v1/convert', api_key, url, json=payload)
+    result = poll_job(body['job_id'], api_key, url)
+
+    output_path = output_path or os.path.splitext(os.path.basename(file_path))[0] + FORMAT_EXTENSIONS[target_format]
+    generated = result.get('content')
+    if generated:
+        with open(output_path, 'w', encoding='utf-8') as f: f.write(generated)
+        click.secho(f"Wrote {output_path}", fg="green")
+    else:
+        click.secho("Warning: server did not return document content to save locally.", fg="yellow")
+
+    redirect_url = result.get('redirect_url')
+    if redirect_url:
+        click.echo(f"Also available in your SudoDocs workspace: {url}{redirect_url}")
+
+@cli.command()
+@click.option('--pr-number', type=int, required=True)
+@click.option('--pr-title', required=True)
+@click.option('--pr-body', required=True)
+@click.option('--pr-author', required=True)
+@click.option('--pr-branch', default=None, help='Head branch name. Required for Screenshot Docflows if your preview URL pattern uses {branch}.')
+@click.option('--pr-sha', default=None, help='Head commit SHA. Required for Screenshot Docflows if your preview URL pattern uses {sha}.')
+@click.option('--screenshot', 'screenshots', multiple=True, metavar='ROUTE=PATH',
+              help='Attach a screenshot your own CI already captured (e.g. from a self-hosted '
+                   'runner with network access SudoDocs cannot reach, such as one behind a VPN). '
+                   'Repeatable. Skips SudoDocs\' own preview-URL capture for this PR entirely. '
+                   'Example: --screenshot /dashboard=./screenshots/dashboard.png')
+def docflow(pr_number, pr_title, pr_body, pr_author, pr_branch, pr_sha, screenshots):
+    """Trigger a Docflows suggestion from a Code PR."""
+    import base64
+
+    api_key, url = load_config()
+    config = (yaml.safe_load(open('sudodocs.yaml')) or {}) if os.path.exists('sudodocs.yaml') else {}
+    if not config.get('integration_id'):
+        click.secho("Error: integration_id must be in sudodocs.yaml", fg="red"); sys.exit(1)
+
+    pr_data = {"number": pr_number, "title": pr_title, "body": pr_body, "author": pr_author, "url": f"https://github.com/pull/{pr_number}"}
+    if pr_branch: pr_data["head_ref"] = pr_branch
+    if pr_sha: pr_data["head_sha"] = pr_sha
+
+    if screenshots:
+        attached = []
+        for entry in screenshots:
+            if '=' not in entry:
+                click.secho(f"Error: --screenshot must be ROUTE=PATH, got: {entry}", fg="red"); sys.exit(1)
+            route, path = entry.split('=', 1)
+            if not os.path.exists(path):
+                click.secho(f"Error: screenshot file not found: {path}", fg="red"); sys.exit(1)
+            with open(path, 'rb') as f:
+                attached.append({
+                    "route": route,
+                    "content": base64.b64encode(f.read()).decode('utf-8'),
+                    "content_encoding": "base64",
+                })
+        pr_data["screenshots"] = attached
+
+    payload = {"integration_id": config['integration_id'], "pr_data": pr_data}
+    body = api_request('POST', '/api/v1/docflows/generate', api_key, url, json=payload)
+    poll_job(body['job_id'], api_key, url, 1800)
+
+@cli.command()
+@click.option('--base-url', default=None, help='Override the SudoDocs API base URL.')
+def login(base_url):
+    """Log in via your browser and save a personal CLI credential (Enterprise plan only)."""
+    url = base_url or resolve_base_url()
+    try:
+        res = requests.post(f"{url}/api/v1/auth/device_code", timeout=15)
+        res.raise_for_status()
+        data = res.json()
+    except requests.exceptions.RequestException as e:
+        click.secho(f"Error: Could not reach {url} ({e})", fg="red")
+        sys.exit(1)
+
+    device_code = data['device_code']
+    interval = data.get('interval', 3)
+    expires_in = data.get('expires_in', 600)
+
+    click.echo(f"Confirm code: {click.style(data['user_code'], fg='cyan', bold=True)}")
+    click.echo(f"Opening {data['verification_url']} in your browser...")
+    try:
+        webbrowser.open(data['verification_url'])
+    except Exception:
+        pass
+    click.echo("Waiting for approval", nl=False)
+
+    start = time.time()
+    while time.time() - start < expires_in:
+        time.sleep(interval)
+        try:
+            res = requests.post(f"{url}/api/v1/auth/token", json={"device_code": device_code}, timeout=15)
+            body = res.json()
+        except requests.exceptions.RequestException:
+            click.echo(".", nl=False)
+            continue
+
+        status = body.get('status')
+        if status == 'approved' and body.get('api_key'):
+            _save_credentials(body['api_key'], url)
+            click.secho("\nLogged in!", fg="green")
+            return
+        if status in ('denied', 'expired'):
+            click.secho(f"\n{body.get('message', 'Login ' + status + '.')}", fg="red")
+            sys.exit(1)
+        click.echo(".", nl=False)
+
+    click.secho("\nTimed out waiting for approval.", fg="red")
+    sys.exit(1)
+
+@cli.command()
+def logout():
+    """Remove the locally saved CLI login."""
+    path = _credentials_path()
+    if os.path.exists(path):
+        os.remove(path)
+        click.secho("Logged out.", fg="green")
+    else:
+        click.echo("Not logged in.")
+
+@cli.command()
+def whoami():
+    """Show who the CLI is currently authenticated as."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/auth/whoami', api_key, url, require_job_id=False)
+    data = body.get('data', {})
+    click.echo(f"Logged in as {data.get('email')} ({data.get('role')}) at {data.get('org_name')} - plan: {data.get('subscription_plan')}")
+
+@cli.group()
+def admin():
+    """System Administrator-only commands (mirrors the Admin Dashboard)."""
+    pass
+
+@admin.group('api-keys')
+def api_keys():
+    """Manage org API keys."""
+    pass
+
+@api_keys.command('create')
+@click.option('--name', default=None, help='Label for the new key (default: "CLI Generated Key").')
+def api_keys_create(name):
+    """Generate a new org API key. The raw key is shown once - copy it immediately."""
+    api_key, url = load_config()
+    body = api_request('POST', '/api/v1/admin/api-keys', api_key, url, require_job_id=False, json={"name": name} if name else {})
+    data = body.get('data', {})
+    click.secho(f"API key created: {data.get('api_key')}", fg="green")
+    click.echo("Copy it now - it will not be shown again.")
+
+@api_keys.command('list')
+def api_keys_list():
+    """List org API keys (never shows the raw key, only id/name/prefix)."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/api-keys', api_key, url, require_job_id=False)
+    keys = body.get('data', [])
+    if not keys:
+        click.echo("No API keys.")
+        return
+    for k in keys:
+        click.echo(f"{k['id']}\t{k['name']}\t{k['prefix']}...\tlast used: {k.get('last_used_at') or 'never'}\tcreated: {k['created_at']}")
+
+@api_keys.command('revoke')
+@click.argument('key_id', type=int)
+def api_keys_revoke(key_id):
+    """Revoke an org API key by ID (see `sudodocs admin api-keys list`)."""
+    api_key, url = load_config()
+    api_request('DELETE', f'/api/v1/admin/api-keys/{key_id}', api_key, url, require_job_id=False)
+    click.secho(f"Revoked API key {key_id}.", fg="green")
+
+VALID_ROLES = ('System Administrator', 'Writer')
+
+@admin.group('users')
+def users():
+    """Manage org users and invitations."""
+    pass
+
+@users.command('list')
+def users_list():
+    """List users in your org."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/users', api_key, url, require_job_id=False)
+    for u in body.get('data', []):
+        click.echo(f"{u['id']}\t{u['email']}\t{u['name']}\t{u['role']}\tjoined: {u['created_at']}")
+
+@users.command('invite')
+@click.option('--email', required=True)
+@click.option('--role', required=True, type=click.Choice(VALID_ROLES))
+def users_invite(email, role):
+    """Invite a user to your org by email."""
+    api_key, url = load_config()
+    body = api_request('POST', '/api/v1/admin/users/invite', api_key, url, require_job_id=False, json={"email": email, "role": role})
+    data = body.get('data', {})
+    click.secho(data.get('message', 'Done.'), fg="green")
+    if data.get('invite_url'):
+        if data.get('email_sent'):
+            click.echo(f"Invite email sent to {email}. Link (in case they don't get it): {data['invite_url']}")
+        else:
+            click.secho(f"Couldn't send the invite email - share this link with {email} directly: {data['invite_url']}", fg="yellow")
+
+@users.command('update-role')
+@click.argument('user_id', type=int)
+@click.option('--role', required=True, type=click.Choice(VALID_ROLES))
+def users_update_role(user_id, role):
+    """Change a user's role."""
+    api_key, url = load_config()
+    api_request('POST', f'/api/v1/admin/users/{user_id}/role', api_key, url, require_job_id=False, json={"role": role})
+    click.secho(f"User {user_id} is now {role}.", fg="green")
+
+@users.command('remove')
+@click.argument('user_id', type=int)
+def users_remove(user_id):
+    """Remove a user from your org (they keep their SudoDocs account, just lose org access)."""
+    api_key, url = load_config()
+    api_request('DELETE', f'/api/v1/admin/users/{user_id}', api_key, url, require_job_id=False)
+    click.secho(f"Removed user {user_id} from your organization.", fg="green")
+
+@users.group('invitations')
+def invitations():
+    """Manage pending invitations."""
+    pass
+
+@invitations.command('list')
+def invitations_list():
+    """List pending invitations for your org."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/invitations', api_key, url, require_job_id=False)
+    invites = body.get('data', [])
+    if not invites:
+        click.echo("No pending invitations.")
+        return
+    for inv in invites:
+        click.echo(f"{inv['id']}\t{inv['email']}\t{inv['role']}\tsent: {inv['created_at']}")
+
+@invitations.command('cancel')
+@click.argument('invite_id', type=int)
+def invitations_cancel(invite_id):
+    """Cancel a pending invitation."""
+    api_key, url = load_config()
+    api_request('DELETE', f'/api/v1/admin/invitations/{invite_id}', api_key, url, require_job_id=False)
+    click.secho(f"Cancelled invitation {invite_id}.", fg="green")
+
+BASE_STYLE_FRAMEWORKS = ('google', 'microsoft', 'apple', 'ibm')
+
+@admin.group('kb')
+def kb():
+    """Manage Knowledge Base configuration."""
+    pass
+
+@kb.command('get')
+def kb_get():
+    """Show the current Knowledge Base configuration."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/kb', api_key, url, require_job_id=False)
+    click.echo(json.dumps(body.get('data', {}), indent=2))
+
+@kb.command('set-base-framework')
+@click.option('--framework', required=True, type=click.Choice(BASE_STYLE_FRAMEWORKS))
+def kb_set_base_framework(framework):
+    """Set the base documentation style framework."""
+    api_key, url = load_config()
+    api_request('POST', '/api/v1/admin/kb/base-framework', api_key, url, require_job_id=False, json={"base_style_framework": framework})
+    click.secho(f"Base framework set to {framework}.", fg="green")
+
+@kb.command('set-product-categories')
+@click.option('--category', 'categories', multiple=True, help='Product category name (repeatable).')
+def kb_set_product_categories(categories):
+    """Set product categories. Shared across Bulk Release Notes and the
+    Feature Draft pipeline's Information Architect step.
+
+    This replaces the full set of categories each call, same as the web form
+    - omitting every --category clears back to just "Other". Looking for
+    deployment tags or CSV column mappings? See `sudodocs release-notes
+    settings set` - those moved there since they're Release-Notes-specific."""
+    api_key, url = load_config()
+    api_request('POST', '/api/v1/admin/kb/product-categories', api_key, url, require_job_id=False, json={"product_categories": list(categories)})
+    click.secho("Product Categories saved.", fg="green")
+
+@kb.command('auto-learn')
+def kb_auto_learn():
+    """Trigger KB auto-learn (analyzes synced content to suggest KB settings)."""
+    api_key, url = load_config()
+    body = api_request('POST', '/api/v1/admin/kb/auto-learn', api_key, url)
+    poll_job(body['job_id'], api_key, url, 600)
+
+REPO_TYPES = ('documentation', 'code', 'web')
+
+@admin.group('integrations')
+def integrations():
+    """Manage repo/doc integrations."""
+    pass
+
+@integrations.command('list')
+def integrations_list():
+    """List integrations for your org."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/integrations', api_key, url, require_job_id=False)
+    for i in body.get('data', []):
+        click.echo(f"{i['id']}\t{i['name']}\t{i.get('repo_type')}\t{i.get('base_url')}")
+
+@integrations.command('create')
+@click.option('--name', required=True)
+@click.option('--base-url', required=True, help='Repository/site URL.')
+@click.option('--repo-type', required=True, type=click.Choice(REPO_TYPES))
+@click.option('--auth-type', type=click.Choice(['pat', 'app']), help='Required unless --repo-type web.')
+@click.option('--service-pat', default=None, help='Personal Access Token (for --auth-type pat).')
+@click.option('--app-id', default=None, help='GitHub App ID (for --auth-type app).')
+@click.option('--installation-id', default=None, help='GitHub App installation ID (for --auth-type app).')
+@click.option('--private-key', default=None, help='GitHub App private key PEM contents (for --auth-type app).')
+def integrations_create(name, base_url, repo_type, auth_type, service_pat, app_id, installation_id, private_key):
+    """Connect a new repo/doc/web integration."""
+    api_key, url = load_config()
+    payload = {"name": name, "base_url": base_url, "repo_type": repo_type, "auth_type": auth_type}
+    if service_pat: payload["service_pat"] = service_pat
+    if app_id: payload["app_id"] = app_id
+    if installation_id: payload["installation_id"] = installation_id
+    if private_key: payload["private_key"] = private_key
+    api_request('POST', '/api/v1/admin/integrations', api_key, url, require_job_id=False, json=payload)
+    click.secho(f"Integration '{name}' created.", fg="green")
+
+@integrations.command('delete')
+@click.argument('integration_id', type=int)
+def integrations_delete(integration_id):
+    """Remove an integration."""
+    api_key, url = load_config()
+    api_request('DELETE', f'/api/v1/admin/integrations/{integration_id}', api_key, url, require_job_id=False)
+    click.secho(f"Integration {integration_id} removed.", fg="green")
+
+@integrations.command('update-token')
+@click.argument('integration_id', type=int)
+@click.option('--new-pat', required=True, help='New Personal Access Token.')
+def integrations_update_token(integration_id, new_pat):
+    """Rotate an integration's Personal Access Token."""
+    api_key, url = load_config()
+    api_request('POST', f'/api/v1/admin/integrations/{integration_id}/token', api_key, url, require_job_id=False, json={"new_pat": new_pat})
+    click.secho(f"Token updated for integration {integration_id}.", fg="green")
+
+@integrations.command('sync-schedule')
+@click.argument('integration_id', type=int)
+@click.option('--hours', type=int, default=None, help='Auto-sync every N hours. Omit to turn automatic sync off (manual sync only).')
+def integrations_sync_schedule(integration_id, hours):
+    """Set or clear an integration's automatic sync schedule."""
+    api_key, url = load_config()
+    api_request('POST', f'/api/v1/admin/integrations/{integration_id}/sync-schedule', api_key, url, require_job_id=False, json={"sync_frequency_hours": hours})
+    click.secho(f"Sync schedule updated for integration {integration_id}.", fg="green")
+
+@integrations.command('webhook')
+@click.argument('integration_id', type=int)
+def integrations_webhook(integration_id):
+    """Show the webhook URL and secret for an integration."""
+    api_key, url = load_config()
+    body = api_request('GET', f'/api/v1/admin/integrations/{integration_id}/webhook', api_key, url, require_job_id=False)
+    data = body.get('data', {})
+    click.echo(f"Webhook URL: {data.get('webhook_url')}")
+    click.echo(f"Webhook Secret: {data.get('webhook_secret')}")
+
+@integrations.command('preview-settings')
+@click.argument('integration_id', type=int)
+@click.option('--url-pattern', default='', help='Preview URL pattern, e.g. https://pr-{pr_number}.preview.example.com. Supports {pr_number}, {branch}, {sha}.')
+@click.option('--auth-type', 'preview_auth_type', type=click.Choice(['none', 'basic', 'header', 'session_cookie', 'form_login']), default='none')
+@click.option('--username', default='', help='For --auth-type basic or form_login.')
+@click.option('--password', default='', help='For --auth-type basic or form_login. Leave unset to keep the existing stored value.')
+@click.option('--header-name', default='', help='For --auth-type header.')
+@click.option('--header-value', default='', help='For --auth-type header. Leave unset to keep the existing stored value.')
+@click.option('--route-map', 'route_maps', multiple=True, metavar='GLOB=>ROUTE1,ROUTE2', help='Map a changed-file glob to preview routes to screenshot (repeatable).')
+@click.option('--session-cookie-name', default='')
+@click.option('--session-cookie-value', default='', help='Leave unset to keep the existing stored value.')
+@click.option('--login-url', default='', help='For --auth-type form_login.')
+@click.option('--login-username-selector', default='')
+@click.option('--login-password-selector', default='')
+@click.option('--login-submit-selector', default='')
+def integrations_preview_settings(integration_id, url_pattern, preview_auth_type, username, password, header_name, header_value, route_maps, session_cookie_name, session_cookie_value, login_url, login_username_selector, login_password_selector, login_submit_selector):
+    """Configure Screenshot Docflows preview settings for an integration."""
+    api_key, url = load_config()
+    route_map = []
+    for entry in route_maps:
+        if '=>' not in entry:
+            click.secho(f"Error: --route-map must be GLOB=>ROUTE1,ROUTE2, got: {entry}", fg="red"); sys.exit(1)
+        file_glob, _, routes_str = entry.partition('=>')
+        route_map.append({"file_glob": file_glob.strip(), "routes": [r.strip() for r in routes_str.split(',') if r.strip()]})
+
+    payload = {
+        "preview_url_pattern": url_pattern,
+        "preview_auth_type": preview_auth_type,
+        "preview_username": username,
+        "preview_password": password,
+        "preview_auth_header_name": header_name,
+        "preview_auth_header_value": header_value,
+        "preview_route_map": route_map,
+        "preview_session_cookie_name": session_cookie_name,
+        "preview_session_cookie_value": session_cookie_value,
+        "preview_login_url": login_url,
+        "preview_login_username_selector": login_username_selector,
+        "preview_login_password_selector": login_password_selector,
+        "preview_login_submit_selector": login_submit_selector,
+    }
+    api_request('POST', f'/api/v1/admin/integrations/{integration_id}/preview-settings', api_key, url, require_job_id=False, json=payload)
+    click.secho(f"Preview settings updated for integration {integration_id}.", fg="green")
+
+@admin.group('services')
+def services():
+    """Connect Jira/Slack service integrations."""
+    pass
+
+@services.command('connect-jira')
+@click.option('--name', required=True)
+@click.option('--jira-url', required=True)
+@click.option('--jira-email', required=True)
+@click.option('--jira-token', required=True)
+def services_connect_jira(name, jira_url, jira_email, jira_token):
+    """Connect a Jira service integration."""
+    api_key, url = load_config()
+    payload = {"provider": "jira", "name": name, "jira_url": jira_url, "jira_email": jira_email, "jira_token": jira_token}
+    api_request('POST', '/api/v1/admin/services/connect', api_key, url, require_job_id=False, json=payload)
+    click.secho("Jira connected.", fg="green")
+
+@services.command('connect-slack')
+@click.option('--name', required=True)
+@click.option('--slack-token', required=True)
+@click.option('--slack-secret', required=True, help="Slack app's signing secret.")
+def services_connect_slack(name, slack_token, slack_secret):
+    """Connect a Slack service integration."""
+    api_key, url = load_config()
+    payload = {"provider": "slack", "name": name, "slack_token": slack_token, "slack_secret": slack_secret}
+    api_request('POST', '/api/v1/admin/services/connect', api_key, url, require_job_id=False, json=payload)
+    click.secho("Slack connected.", fg="green")
+
+LLM_PROVIDERS = ('gemini', 'openai', 'claude', 'deepseek', 'custom_openai_compatible')
+EMBEDDING_PROVIDERS = ('gemini', 'openai', 'voyage', 'custom_openai_compatible')
+
+@admin.group('llm-provider')
+def llm_provider():
+    """Configure BYOK (Bring Your Own Key) LLM/embedding providers."""
+    pass
+
+@llm_provider.command('get')
+def llm_provider_get():
+    """Show the currently configured providers (never shows the raw key)."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/llm-provider', api_key, url, require_job_id=False)
+    click.echo(json.dumps(body.get('data', {}), indent=2))
+
+@llm_provider.command('set-generation')
+@click.option('--provider-type', required=True, type=click.Choice(LLM_PROVIDERS))
+@click.option('--api-key', 'provider_api_key', required=True)
+@click.option('--model-name', required=True)
+@click.option('--base-url', default=None, help='Required for --provider-type custom_openai_compatible.')
+def llm_provider_set_generation(provider_type, provider_api_key, model_name, base_url):
+    """Set the text-generation LLM provider."""
+    api_key, url = load_config()
+    payload = {"provider_type": provider_type, "api_key": provider_api_key, "model_name": model_name, "base_url": base_url}
+    api_request('POST', '/api/v1/admin/llm-provider/generation', api_key, url, require_job_id=False, json=payload)
+    click.secho("Text generation provider saved.", fg="green")
+
+@llm_provider.command('set-embeddings')
+@click.option('--provider-type', required=True, type=click.Choice(EMBEDDING_PROVIDERS))
+@click.option('--api-key', 'provider_api_key', required=True)
+@click.option('--model-name', required=True)
+@click.option('--base-url', default=None, help='Required for --provider-type custom_openai_compatible.')
+def llm_provider_set_embeddings(provider_type, provider_api_key, model_name, base_url):
+    """Set the embeddings/search provider."""
+    api_key, url = load_config()
+    payload = {"provider_type": provider_type, "api_key": provider_api_key, "model_name": model_name, "base_url": base_url}
+    api_request('POST', '/api/v1/admin/llm-provider/embeddings', api_key, url, require_job_id=False, json=payload)
+    click.secho("Embeddings & search provider saved.", fg="green")
+
+@admin.group('sso')
+def sso():
+    """Configure SSO (Enterprise)."""
+    pass
+
+@sso.command('get')
+def sso_get():
+    """Show the current SSO configuration (never shows the client secret)."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/sso', api_key, url, require_job_id=False)
+    data = body.get('data')
+    if not data:
+        click.echo("SSO not configured.")
+        return
+    click.echo(json.dumps(data, indent=2))
+
+@sso.command('set')
+@click.option('--domain', required=True, help='Email domain that should be routed to SSO, e.g. company.com.')
+@click.option('--client-id', required=True)
+@click.option('--client-secret', required=True)
+@click.option('--issuer-url', required=True)
+def sso_set(domain, client_id, client_secret, issuer_url):
+    """Configure SSO for your org."""
+    api_key, url = load_config()
+    payload = {"domain": domain, "client_id": client_id, "client_secret": client_secret, "issuer_url": issuer_url}
+    api_request('POST', '/api/v1/admin/sso', api_key, url, require_job_id=False, json=payload)
+    click.secho("SSO configuration saved.", fg="green")
+
+@admin.group('doc-team-roles')
+def doc_team_roles():
+    """Information Architect / Technical Writer / Editor instructions (the
+    Admin Dashboard's "Roles" tab - separate from Knowledge Base)."""
+    pass
+
+@doc_team_roles.command('get')
+def doc_team_roles_get():
+    """Show the org's current doc-team role instructions (blank = using the built-in default for that role)."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/admin/doc-team-roles', api_key, url, require_job_id=False)
+    click.echo(json.dumps(body.get('data', {}), indent=2))
+
+@doc_team_roles.command('set')
+@click.option('--information-architect', default='', help='Instructions/prompt for the Information Architect role.')
+@click.option('--technical-writer', default='', help='Instructions/prompt for the Technical Writer role.')
+@click.option('--editor', default='', help='Instructions/prompt for the Editor role.')
+def doc_team_roles_set(information_architect, technical_writer, editor):
+    """Set doc-team role instructions. Leaving an option blank uses the built-in default for that role, same as leaving its box empty on the web form."""
+    api_key, url = load_config()
+    payload = {"information_architect": information_architect, "technical_writer": technical_writer, "editor": editor}
+    api_request('POST', '/api/v1/admin/doc-team-roles', api_key, url, require_job_id=False, json=payload)
+    click.secho("Doc team role instructions saved.", fg="green")
+
+@admin.group('jobs')
+def jobs():
+    """Manage background jobs."""
+    pass
+
+@jobs.command('cancel')
+@click.argument('job_id')
+def jobs_cancel(job_id):
+    """Cancel a running/pending background job."""
+    api_key, url = load_config()
+    api_request('POST', f'/api/v1/admin/jobs/{job_id}/cancel', api_key, url, require_job_id=False)
+    click.secho(f"Stopping job {job_id}...", fg="green")
+
+@cli.group('style-guide')
+def style_guide():
+    """Neural Style Guide overrides: free-form Markdown (product overview, style
+    guide, writing instructions) injected into every AI writing task on top of
+    the base framework. Available to any doc-team member (Writer or System
+    Administrator), same as the Admin Dashboard's KB tab -> Neural Overrides."""
+    pass
+
+@style_guide.command('get')
+@click.option('--output', '-o', 'output_path', type=click.Path(), default=None, help='Write to a local file instead of stdout.')
+def style_guide_get(output_path):
+    """Show the org's current Neural Style Guide overrides."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/kb/style-guide', api_key, url, require_job_id=False)
+    content = body.get('data', {}).get('neural_style_md', '')
+    if output_path:
+        with open(output_path, 'w', encoding='utf-8') as f: f.write(content)
+        click.secho(f"Wrote {output_path}", fg="green")
+    else:
+        click.echo(content)
+
+@style_guide.command('set')
+@click.argument('file_path', type=click.Path(exists=True))
+def style_guide_set(file_path):
+    """Upload a local Markdown file as the org's Neural Style Guide overrides (replaces the existing content, same as saving the web form)."""
+    api_key, url = load_config()
+    with open(file_path, 'r', encoding='utf-8') as f:
+        content = f.read()
+    api_request('POST', '/api/v1/kb/style-guide', api_key, url, require_job_id=False, json={"neural_style_md": content})
+    click.secho(f"Style guide overrides saved from {file_path}.", fg="green")
+
+@cli.group('release-notes')
+def release_notes():
+    """Bulk Release Notes generation settings. Available to any doc-team
+    member (Writer or System Administrator)."""
+    pass
+
+@release_notes.group('settings')
+def release_notes_settings():
+    """Deployment tags and CSV column mappings - both optional."""
+    pass
+
+@release_notes_settings.command('get')
+def release_notes_settings_get():
+    """Show the org's current Release Notes settings (blank fields use built-in defaults)."""
+    api_key, url = load_config()
+    body = api_request('GET', '/api/v1/release-notes/settings', api_key, url, require_job_id=False)
+    click.echo(json.dumps(body.get('data', {}), indent=2))
+
+@release_notes_settings.command('set-tags')
+@click.option('--tag', 'tags', multiple=True, help='Deployment tag (repeatable). Pass none to clear back to the defaults (Cloud, On-Premise, Both).')
+def release_notes_settings_set_tags(tags):
+    """Set deployment tags. Doesn't touch CSV column mappings."""
+    api_key, url = load_config()
+    api_request('POST', '/api/v1/release-notes/settings', api_key, url, require_job_id=False, json={"deployment_tags": list(tags)})
+    click.secho("Deployment tags saved.", fg="green")
+
+@release_notes_settings.command('set-csv-key')
+@click.option('--header', 'headers', multiple=True, help='CSV column header(s) that map to the ticket ID/key (repeatable). Pass none to clear back to the default header names.')
+def release_notes_settings_set_csv_key(headers):
+    """Set the CSV column mapping for the ticket ID/key. Doesn't touch tags or the other mappings."""
+    api_key, url = load_config()
+    api_request('POST', '/api/v1/release-notes/settings', api_key, url, require_job_id=False, json={"csv_key": list(headers)})
+    click.secho("CSV key mapping saved.", fg="green")
+
+@release_notes_settings.command('set-csv-summary')
+@click.option('--header', 'headers', multiple=True, help='CSV column header(s) that map to the summary (repeatable). Pass none to clear back to the default header names.')
+def release_notes_settings_set_csv_summary(headers):
+    """Set the CSV column mapping for the summary. Doesn't touch tags or the other mappings."""
+    api_key, url = load_config()
+    api_request('POST', '/api/v1/release-notes/settings', api_key, url, require_job_id=False, json={"csv_summary": list(headers)})
+    click.secho("CSV summary mapping saved.", fg="green")
+
+@release_notes_settings.command('set-csv-description')
+@click.option('--header', 'headers', multiple=True, help='CSV column header(s) that map to the description (repeatable). Pass none to clear back to the default header names.')
+def release_notes_settings_set_csv_description(headers):
+    """Set the CSV column mapping for the description. Doesn't touch tags or the other mappings."""
+    api_key, url = load_config()
+    api_request('POST', '/api/v1/release-notes/settings', api_key, url, require_job_id=False, json={"csv_description": list(headers)})
+    click.secho("CSV description mapping saved.", fg="green")
+
+if __name__ == '__main__':
+    cli()

sudodocs_cli-1.0.0/sudodocs_cli.egg-info/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: sudodocs-cli
+Version: 1.0.0
+Summary: Command-line interface and Headless API client for SudoDocs
+Author: SudoDocs
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://sudodocs.com
+Project-URL: Documentation, https://docs.sudodocs.com/docs/cli-guide
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1.7
+Requires-Dist: requests>=2.31.0
+Requires-Dist: PyYAML>=6.0.1
+
+# sudodocs-cli
+
+Command-line interface and Headless API client for [SudoDocs](https://sudodocs.com) - automated documentation for technical teams. Trigger repository syncs, convert specs to docs, manage your Knowledge Base, and administer users, integrations, and settings from a terminal or CI/CD pipeline instead of the dashboard.
+
+**Requires a SudoDocs Enterprise plan.** The CLI is an Enterprise-only feature - every command authenticates against your organization's SudoDocs account and fails with an upgrade message on other plans.
+
+## Install
+
+```bash
+pip install sudodocs-cli
+```
+
+## Quick Start
+
+```bash
+sudodocs login              # opens your browser to approve a device login
+sudodocs whoami              # confirm who you're logged in as
+sudodocs sync --integration-id 42
+```
+
+See the full [CLI Tasks documentation](https://docs.sudodocs.com/docs/cli-guide) for every available command, one page per SudoDocs feature it automates.
+
+## License
+
+Proprietary - use of this tool is governed by the [SudoDocs Terms of Service](https://sudodocs.com). Source is provided for transparency and issue reporting, not for redistribution or reuse outside SudoDocs.

sudodocs_cli-1.0.0/sudodocs_cli.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+sudodocs_cli/__init__.py
+sudodocs_cli/main.py
+sudodocs_cli.egg-info/PKG-INFO
+sudodocs_cli.egg-info/SOURCES.txt
+sudodocs_cli.egg-info/dependency_links.txt
+sudodocs_cli.egg-info/entry_points.txt
+sudodocs_cli.egg-info/requires.txt
+sudodocs_cli.egg-info/top_level.txt

sudodocs_cli-1.0.0/sudodocs_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sudodocs_cli-1.0.0/sudodocs_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sudodocs = sudodocs_cli.main:cli

sudodocs_cli-1.0.0/sudodocs_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.1.7
+requests>=2.31.0
+PyYAML>=6.0.1

sudodocs_cli-1.0.0/sudodocs_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+sudodocs_cli