git-glimpse-cli 0.1.0__py3-none-any.whl

git_glimpse_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: git-glimpse-cli
+Version: 0.1.0
+Summary: CLI tool to manage and update shared GitHub repos with GitGlimpse.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.2
+Dynamic: license-file
+
+# GitGlimpse CLI
+
+![GitHub release](https://img.shields.io/github/v/release/sutaC/git-glimpse-cli)
+![GitHub last commit](https://img.shields.io/github/last-commit/sutaC/git-glimpse-cli)
+![License](https://img.shields.io/github/license/sutaC/git-glimpse-cli)
+
+A command-line interface to manage, synchronize, and monitor shared GitHub repositories via the GitGlimpse platform.
+
+---
+
+**GitGlimpse website:** [gitglimpse.sutac.pl](https://gitglimpse.sutac.pl/)
+
+**GitGlimpse on GitHub:** [github.com/sutaC/git-glimpse-cli](https://github.com/sutaC/git-glimpse-cli/)
+
+**Author:** [sutaC](https://github.com/sutaC)
+
+## Installation
+
+Install the latest version globally via pip:
+
+```bash
+pip install git-glimpse-cli
+```
+
+## Quickstart
+
+1. Log in with your GitGlimpse CLI token. It will be saved to your global user configuration.
+    > You will be able to create one on your GitGlimpse user panel at https://gitglimpse.sutac.pl/user#hCliTokens
+    ```bash
+    glimpse login <YOUR_API_TOKEN>
+    ```
+2. Initialize a Repository.
+    > Navigate to your local Git repository, ensure it is uplaoded to GitHub and link it to GitGlimpse. This creates a .shared-repo.json file to track the project.
+    ```bash
+    cd my-project
+    glimpse init <new/link>
+    ```
+3. Check status.
+    ```bash
+    glimpse status
+    ```
+4. Schedule the build to update GitGlimpse display.
+    ```bash
+    glimpse build
+    ```
+
+## Configuration
+
+GitGlimpse CLI uses holds your configuration at `~/.config/glimpsecli/config.json`, and local repository settings are stored at `./.shared-repo.json`.
+
+### Advanced Settings
+
+| Command                  | Description                                                                 |
+| ------------------------ | --------------------------------------------------------------------------- |
+| `glimpse config debug`   | Enables verbose debug mode, printing stack traces.                          |
+| `glimpse config set-url` | Overrides the default production server with a custom backend or localhost. |
+
+## Development
+
+1. Clone the repository and install it in editable mode:
+    ```bash
+    git clone https://github.com/sutaC/git-glimpse-cli.git
+    cd git-glimpse-cli
+    python3 -m venv .venv
+    source .venv/bin/activate
+    pip install -e .
+    ```
+2. Point the CLI to your local development server:
+    ```bash
+    glimpse config set-url http://localhost:5000
+    ```

git_glimpse_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+git_glimpse_cli-0.1.0.dist-info/licenses/LICENSE,sha256=SA_CO5U6vlMWqdujOQQk937USavr3DPXj0_bPykzIFA,1082
+glimpsecli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+glimpsecli/api.py,sha256=bqlaNn8dLhCqwVcZA7HAOjInbPoWSwidgC8tqjOWY0U,2808
+glimpsecli/config.py,sha256=bJcCfwr8pIxJq93lXdTIV7-i_DrTyzGHsW6V6mA2mdQ,3163
+glimpsecli/helpers.py,sha256=yoX6luwJm8pB5SNJ43dNGB1iPTvrzbX-xjKZMI6JXUE,3820
+glimpsecli/main.py,sha256=RrEAUG6jkG6mDpXRs76ZPGJZaIzGiV8rBDLXKHBeEq4,11030
+glimpsecli/utils.py,sha256=SB7hPXeODxzGjRcBDxv_HmyntXZvwlohSal5IOLbpnQ,3784
+git_glimpse_cli-0.1.0.dist-info/METADATA,sha256=hvAa_TCgpG722XrfX__6uRYUdUTWr7rH6U0aBWbMGqI,2722
+git_glimpse_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+git_glimpse_cli-0.1.0.dist-info/entry_points.txt,sha256=Je6nkOo21o_sdUM62LH8Ga1xyIkz2P3_Y7WVBE_L3SI,48
+git_glimpse_cli-0.1.0.dist-info/top_level.txt,sha256=XFyNCeBJ8s5QzHm848zADPh0fjK6EOgV9o2wvJGMhV8,11
+git_glimpse_cli-0.1.0.dist-info/RECORD,,

git_glimpse_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_glimpse_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+glimpse = glimpsecli.main:cli

git_glimpse_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antoni "sutaC" Siekański
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_glimpse_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+glimpsecli

glimpsecli/api.py

@@ -0,0 +1,71 @@
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from glimpsecli import config, helpers
+from contextlib import nullcontext
+from json import JSONDecodeError
+from rich import print
+import typer
+import httpx
+
+def request_api(
+        endpoint: str,
+        method: str = "GET",
+        token: str | None = None, 
+        handle_codes: list[int] = [200],
+        payload: dict | None = None,
+        quiet=False
+    ) -> httpx.Response:
+    """Requests GitGlimpse api.
+    
+    Args:
+        endpoint: Path for api call (should not include `{API_BASE}/cli`).
+        method: Http metod to use.
+        token: GitGlimpse api token (if not provided will prompt user).
+        handle_codes: Response codes on which function will return response.
+        payload: Json payload.
+        quiet: Flag for disabling default progess spinner.
+
+    Returns:
+        Response from api.
+    """
+    if not token:
+        token = helpers.get_token()
+    url = f"{config.get_api_url()}{endpoint}"
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True) if not quiet else nullcontext() as progress:
+        if progress: 
+            progress.add_task(description="[bold green]Connecting to server...[/bold green]", total=None)
+        try:
+            response = httpx.request(
+                method,
+                url,
+                headers={"Authorization": f"Bearer {token}"}, 
+                timeout=10.0,
+                json=payload
+            )
+        except httpx.RequestError:
+            print("[bold red]Connection error: Could not reach the server.")
+            raise typer.Exit(1)
+    if response.status_code in handle_codes:
+        return response
+    elif response.status_code == 401:
+        print("[bold red]Authentication failed: Invalid or revoked token.[/bold red]")
+        try:
+            error = response.json().get("error")
+            if error: print(f"[dim]Error reason: {error}[/dim]")
+        except JSONDecodeError: pass
+        config.cliconf_save(token="")
+        print("[yellow]Your session has expired. Please run 'glimpse login' again [/yellow].")
+        raise typer.Exit(1)
+    elif response.status_code == 403:
+        print("[bold red]Authentication failed: Invalid or revoked token.[/bold red]")
+        try:
+            error = response.json().get("error")
+            if error: print(f"[dim]Error reason: {error}[/dim]")
+        except JSONDecodeError: pass
+        raise typer.Exit(1)
+    else: 
+        print(f"[bold red]Unexpected error ocurred.\n[dim](status code: {response.status_code})[/dim][/bold red]")
+        try:
+            error = response.json().get("error")
+            if error: print(f"[dim red]Error reason: {error}[/dim red]")
+        except JSONDecodeError: pass
+        raise typer.Exit(1)

glimpsecli/config.py

@@ -0,0 +1,116 @@
+from typing import TypedDict
+from pathlib import Path
+import json
+import os
+
+CLI_CONFIG_DIR = Path.home() / ".config" / "glimpsecli"
+CLI_CONFIG_FILE = CLI_CONFIG_DIR / "config.json"
+CONFIG_FILENAME = ".shared-repo.json"
+DEFAULT_API_URL = "https://gitglimpse.sutac.pl"
+
+# --- repository config
+class RepoConfig(TypedDict):
+    repo_id: str
+
+def repoconf_save(repo_id: str, path: Path = Path(".")) -> None:
+    """Saves repository config to file.
+    
+    Args:
+        repo_id: Repository GitGlimpse id.
+        path: Path to directory holding config file.    
+    """
+    config_path = path / CONFIG_FILENAME
+    conf: RepoConfig = {"repo_id": repo_id}
+    with open(config_path, "w") as f:
+        json.dump(conf, f, indent=2)
+
+def repoconf_load(path: Path = Path(".")) -> RepoConfig | None:
+    """Loads repository config from file.
+    
+    Args:
+        path: Path to directory holding config file.    
+
+    Returns:
+        RepoConfig if avaliable, else None.
+    """
+    config_path = path / CONFIG_FILENAME
+    if not config_path.exists():
+        return None
+    try:
+        with open(config_path, "r") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+def repoconf_remove(path: Path = Path(".")) -> None:
+    """Removes repository config file if exists.
+    
+    Args:
+        path: Path to directory holding config file.
+    """
+    config_path = path / CONFIG_FILENAME
+    config_path.unlink(missing_ok=True)        
+
+# --- cli config
+class CliConfig(TypedDict, total=False):
+    token: str
+    api_url: str
+    debug: bool
+
+def cliconf_save(
+        token: str | None = None, 
+        api_url: str | None = None,
+        debug: bool | None = None
+    ) -> None:
+    """Saves or updates cli config safely.
+    
+    Args:
+        token: GitGlimpse api token.
+    """
+    CLI_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    conf = cliconf_load() or {}
+    if token is not None:
+        if token: conf["token"] = token
+        elif "token" in conf: conf.pop("token")
+    if api_url is not None:
+        if api_url: conf["api_url"] = api_url.rstrip("/")
+        elif "api_url" in conf: conf.pop("api_url")
+    if debug is not None:
+        conf["debug"] = debug
+    with open(CLI_CONFIG_FILE, "w") as f:
+        json.dump(conf, f, indent=2)
+
+def cliconf_load() -> CliConfig | None:
+    """Loads cli configfrom  file.
+    
+    Returns:
+        CliConfig if avaliable, else None.
+    """
+    if not CLI_CONFIG_FILE.exists():
+        return None
+    try: 
+        with open(CLI_CONFIG_FILE, "r") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+def cliconf_remove() -> None:
+    """Removes cli config file."""
+    CLI_CONFIG_FILE.unlink(missing_ok=True)
+
+def get_api_url() -> str:
+    """Resolves active api url
+    
+    Returns:
+        Active api url.
+    """
+    if conf := cliconf_load():
+        if user_url := conf.get("api_url"):
+            return user_url.rstrip("/")
+    return DEFAULT_API_URL
+
+def get_debug_mode() -> bool:
+    """Returns True if debug is enabled in user config, else False."""
+    if conf := cliconf_load():
+        return conf.get("debug", False)
+    return False

glimpsecli/helpers.py

@@ -0,0 +1,97 @@
+from glimpsecli import utils, config, api
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from pathlib import Path
+from rich import print
+import typer
+import time
+
+
+def get_or_prompt_url(url: str | None = None, detect: bool = True) -> str:
+    """Helper to get GitHub repository url.
+    
+    Args:
+        url: GitHub repository url.
+        detect: Flag for automatic detection.
+
+    Returns:
+        GitHub repository url.
+    """
+    if detect and not url:
+        if not Path(".git").exists():
+            print("[red]Error: Current directory is not a Git repository.[/red]")
+            raise typer.Exit(1)
+        url = utils.get_git_remote_url()
+        if not url:
+            print("[dim]Could not detect GitHub url.[/dim]")
+    if not url:
+        while True:
+            url = typer.prompt("Enter GitHub repository URL (e.g., https://github.com/user/repo.git)")
+            if url: url = url.strip()
+            if url and utils.is_valid_repo_url(url): break
+            print("[bold red]Invalid url, try again...[/bold red]")
+    return url
+
+def finalize_init(repo_id: str) -> None:
+    """Helper to save config and update gitignore.
+    
+    Args:
+        repo_id: Repository GitGlimpse id.
+    """
+    # Add repo id to local file
+    config.repoconf_save(repo_id)
+    print("[dim]Created local .shared-repo.json configuration file for this repository.[/dim]")
+    # Auto-add to .gitignore
+    gitignore = Path(".gitignore")
+    ignore_entry = "\n.shared-repo.json\n"
+    if gitignore.exists():
+        if ".shared-repo.json" not in gitignore.read_text():
+            with open(gitignore, "a") as f:
+                f.write(ignore_entry)
+            print("[dim]Added .shared-repo.json to .gitignore[/dim]")
+    else:
+        gitignore.write_text(ignore_entry)
+        print("[dim]Created .gitignore and added .shared-repo.json[/dim]")
+
+def poll_build_status(token: str, repo_id: str) -> None:
+    """Helper to poll build status from server.
+    
+    Args:
+        token: GitGlimpse api token.
+        repo_id: Repository GitGlimpse id.
+    """
+    print(f"[dim]Repository build was queued.[/dim]")
+    try:
+        with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True) as progress:
+            task_id = progress.add_task(description="Connecting to server...", total=None)
+            last_status = None
+            while True:
+                poll_response = api.request_api(f"/repos/build/{repo_id}/status", token=token, quiet=True) 
+                status = poll_response.json().get("status")
+                if status != last_status:
+                    progress.update(task_id, description=f"Build status: {utils.enrich_status(status)}")
+                    last_status = status
+                    if status in ["success", "failed", "violation"]: break
+                time.sleep(2)
+    except KeyboardInterrupt:
+        print("\n[yellow]Polling interrupted. The build is still running on the server.[/yellow]")
+        print(f"Check status later at: {config.get_api_url()}/repos/details/{repo_id}")
+        raise typer.Exit(0)
+    print(f"Build has finished with status: {utils.enrich_status(status)}")
+    print(f"View details at: {config.get_api_url()}/repos/details/{repo_id}")
+
+def get_repo_config() -> config.RepoConfig:
+    """Helper for getting repository config."""
+    conf = config.repoconf_load()
+    if not conf:
+        print("[yellow]Not initialised. Run 'glimpse init' first.[/yellow]")
+        raise typer.Exit(1)
+    return conf
+
+def get_token() -> str:
+    """Helper for getting api token."""
+    conf = config.cliconf_load() or {}
+    token = conf.get("token")
+    if not conf or not token:
+        print("[yellow]Not logged in. Run 'glimpse login' first.[/yellow]")
+        raise typer.Exit(code=1)
+    return token

glimpsecli/main.py

@@ -0,0 +1,270 @@
+from glimpsecli import config, utils, api, helpers
+from json import JSONDecodeError
+from rich.panel import Panel
+from rich import print
+import importlib.metadata
+import typer
+import sys
+
+_DEBUG_MODE = True
+
+app = typer.Typer(help="CLI tool to manage and update shared GitHub repos with GitGlimpse.", no_args_is_help=True)
+
+# --- main
+def version_callback(value: bool) -> None:
+    """Display version of package."""
+    if not value: return
+    version = importlib.metadata.metadata("git-glimpse-cli").get("version")
+    print(f"GitGlimpse CLI version: {version or "?"}")
+    raise typer.Exit(0)
+
+@app.callback()
+def main(
+        version: bool = typer.Option(None, "--version", callback=version_callback, is_eager=True, help="Display version of package.")
+    ):
+    """GitGlimpse CLI."""
+    pass
+
+# --- login
+@app.command()
+def login(
+    token: str = typer.Option(
+        ..., 
+        prompt="Enter your CLI token", 
+        hide_input=True, 
+        help="Your personal access cli token from dashboard."),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing session without prompting.")
+    ):
+    """Authenticate cli with server."""
+    conf = config.cliconf_load()
+    if not force and conf and conf.get("token"):
+        print("[yellow]You are already logged in.[/yellow]")
+        if not typer.confirm("Do you want to overwrite your existing session?"):
+            print("[dim]Login cancelled.[/dim]")
+            raise typer.Exit(0)
+    response = api.request_api("/cli/user", token=token)
+    config.cliconf_save(token)
+    username =  response.json().get("username")
+    print(f"[bold green]Success![/bold green] Authenticated as [cyan]{username}[/cyan].")
+
+# --- whoami
+@app.command()
+def whoami():
+    """Check the currently logged-in user."""
+    response = api.request_api("/cli/user")
+    username =  response.json().get("username")
+    print(f"Authenticated as [cyan]{username}[/cyan].")
+
+# --- logout
+@app.command()
+def logout():
+    """Clear stored local credentials."""
+    conf = config.cliconf_load()
+    if not conf or not conf.get("token"):
+        print("[yellow]You are not currently logged in.[/yellow]")
+        raise typer.Exit(0)
+    config.cliconf_save(token="")
+    print("[bold green]Logged out successfully.[/bold green]\nStored credentials removed.")
+
+# --- init
+init_app = typer.Typer(help="Link or upload the current Git repository to GitGlimpse server.", no_args_is_help=True)
+app.add_typer(init_app, name="init")
+
+@init_app.command("link")
+def init_link(
+        url: str | None = typer.Option(None, help="GitHub repository URL."),
+        detect: bool = typer.Option(True, help="Do you want to detect repository url automatically.")
+    ):
+    """Link current Git repository to existing one on GitGlimpse."""
+    token = helpers.get_token()
+    if config.repoconf_load():
+        print("Shared repository already initialised.")
+        raise typer.Exit(0)
+    url = helpers.get_or_prompt_url(url, detect)
+    print("[dim]Linking to existing GitGlimpse repository.[/dim]")
+    response = api.request_api("/cli/repos/fetch", method="POST", payload={"url": url}, token=token, handle_codes=[200, 404])
+    if response.status_code == 404:
+        print(f"[bold red]Could not find this repository ([cyan]'{url}'[/cyan]) on GitGlimpse server, provide a valid url.[/bold red]")
+        raise typer.Exit(1)
+    # response.status_code == 200
+    repo_id = response.json().get('repo_id')
+    print("[green]Repo was found on GitGlimpse server.[/green]")
+    helpers.finalize_init(repo_id)
+    print(f"Repository details: {config.get_api_url()}/repos/details/{repo_id}")
+
+@init_app.command("new")
+def init_new(
+    url: str | None = typer.Option(None, help="GitHub repository URL."),
+    is_private: bool | None = typer.Option(None, "--private/--public", help="Is repository public or private?"),
+    force: bool = typer.Option(False, "--force", "-f", help="Upload without prompting about GitHub publish."),
+    detect: bool = typer.Option(True, help="Do you want to detect repository url automatically.")
+    ):
+    """Upload and register current Git repository to GitGlimpse."""
+    token = helpers.get_token()
+    if config.repoconf_load():
+        print("Shared repository already initialised.")
+        raise typer.Exit(0)
+    url = helpers.get_or_prompt_url(url, detect)
+    print("[dim]Adding repository to GitGlimpse.[/dim]")
+    if not force:
+        print("[bold]This repository have to be uploaded to GitHub under given url first.[/bold]")
+        typer.confirm("Continue?", abort=True)
+    # Private/Public
+    if is_private is None:
+        is_private = typer.confirm("Are you uploading a private repository? (This will require SSH key generation)")
+    if is_private: # Private
+        print("[dim]Generating local SSH keys at '.git/shared_repo_keys/'.[/dim]")
+        try:
+            private_key, public_key = utils.generate_local_ssh_key()
+        except Exception as e:
+            print(f"[red]Failed to generate local SSH key: {e}[/red]")
+            raise typer.Exit(code=1)
+        print("\n[bold yellow]Action Required:[/bold yellow] Add this deploy key to your GitHub repository settings ([dim]Settings > Deploy keys > Add deploy key[/dim]):")
+        print(Panel(public_key, title="Public Deploy Key", border_style="yellow"))
+        typer.confirm("Continue?", abort=True)
+        if url.startswith("https://"):
+            url = utils.create_alt_repo_url(url)
+    else: # Public
+        if not url.startswith("https://"):
+            url = utils.create_alt_repo_url(url)
+        private_key = None
+    # Upload
+    response = api.request_api(
+        "/cli/repos/add", 
+        method="POST", 
+        payload={"url": url, "ssh_key": private_key}, 
+        token=token, 
+        handle_codes=[202, 409, 420]
+    )
+    if response.status_code == 409:
+        print(f"[yellow]This repository is already registered on the server.[/yellow]")
+        raise typer.Exit(1)
+    elif response.status_code == 420:
+        print(f"[yellow]You have reached your usage limits.[/yellow]")
+        try:
+            error = response.json().get("error")
+            if error: print(f"[dim]Error reason: {error}[/dim]")
+        except JSONDecodeError: pass
+        raise typer.Exit(1)
+    # response.status_code == 202
+    data = response.json()
+    repo_id = data.get('repo_id')
+    helpers.finalize_init(repo_id)
+    helpers.poll_build_status(token, repo_id)
+
+# --- limits
+@app.command()
+def limits():
+    """Display user build and repository limits."""
+    response = api.request_api("/cli/user/limits")
+    data = response.json()
+    repo_limit = data.get("repo_limit")
+    repo_count = data.get("repo_count")
+    build_limit = data.get("build_limit")
+    build_count = data.get("build_count")
+    print("[bold]User limits:[/bold]")
+    repo_str = f"[red]{repo_count}[/red]/[red]{repo_limit}[/red]" if repo_count == repo_limit else f"{repo_count}/{repo_limit}"
+    print(f"Repositories: {repo_str}")
+    build_str = f"[red]{build_count}[/red]/[red]{build_limit}[/red]" if build_count == build_limit else f"{build_count}/{build_limit}"
+    print(f"Builds: {build_str}")
+
+# --- status
+@app.command()
+def status():
+    """Display status info of current repository."""
+    token = helpers.get_token()
+    conf = helpers.get_repo_config()
+    response = api.request_api(f"/cli/repos/build/{conf['repo_id']}/status", token=token)
+    data = response.json()
+    build_status =  data.get("status", "")
+    print(f"Repository id: [dark_cyan]{conf['repo_id']}[/dark_cyan]")
+    print(f"Build status: {utils.enrich_status(build_status)}")
+    print(f"Repository details: {config.get_api_url()}/repos/details/{conf['repo_id']}")
+
+# --- remove
+@app.command()
+def remove(
+        force: bool = typer.Option(False, "--force", "-f", help="Remove without prompting.")
+    ):
+    """Remove current repository from GitGlimpse."""
+    token = helpers.get_token()
+    conf = helpers.get_repo_config()
+    print(f"[dim]Current repository id: '{conf['repo_id']}'[/dim]")
+    if not force: typer.confirm(f"Are you sure, you want to remove this repository from GitGlimpse?", abort=True)
+    api.request_api(f"/cli/repos/remove/{conf['repo_id']}", method="POST", token=token, handle_codes=[204])
+    config.repoconf_remove()
+    print("Removed repository from GitGlimpse.")
+
+# --- build
+@app.command()
+def build(
+        force: bool = typer.Option(False, "--force", "-f", help="Schedule without prompting.")
+    ):
+    """Schedule a build for current repository."""
+    token = helpers.get_token()
+    conf = helpers.get_repo_config()
+    if not force:
+        print("Ensure that you pushed recent changes to GitHub.")
+        typer.confirm("Continue?", abort=True)
+    print(f"[dim]Scheduling a build for current repository (id: '{conf['repo_id']}')[/dim]")
+    response = api.request_api(f"/cli/repos/build/{conf['repo_id']}", method="POST", token=token, handle_codes=[202, 420, 425])
+    if response.status_code == 420:
+        print(f"[yellow]You have reached your usage limits.[/yellow]")
+        try:
+            error = response.json().get("error")
+            if error: print(f"[dim]Error reason: {error}[/dim]")
+        except JSONDecodeError: pass
+        raise typer.Exit(1)
+    elif response.status_code == 425:
+        print(f"[yellow]This repository already has a pending build.[/yellow]")
+        raise typer.Exit(1)
+    # response.status_code == 202
+    helpers.poll_build_status(token, conf['repo_id'])
+
+# --- config
+config_app = typer.Typer(help="Configure your cli.", no_args_is_help=True)
+app.add_typer(config_app, name="config")
+
+@config_app.command("set-url")
+def config_set_url(
+    url: str = typer.Argument(..., help="Api base url (e.g., http://localhost:8000 or https://gitglimpse.sutac.pl)")
+):
+    """Set the active api server url."""
+    config.cliconf_save(api_url=url)
+    if url:
+        print(f"Api url updated to: {url}")
+    else:
+        print("Api url unset.")
+
+@config_app.command("get-url")
+def config_get_url():
+    """Get the active api server url."""
+    conf = config.cliconf_load() or {}
+    url = conf.get("api_url")
+    if url: print(url)
+
+@config_app.command("debug")
+def config_debug(
+    enabled: bool = typer.Argument(..., help="True to enable debug mode, False to disable.")
+):
+    """Enable or disable verbose debug output and full crash stack traces."""
+    config.cliconf_save(debug=enabled)
+    status = "[bold green]enabled[/bold green]" if enabled else "[bold yellow]disabled[/bold yellow]"
+    print(f"Debug mode {status}.")
+
+# ---
+def cli():
+    try:
+        app()
+    except Exception as exc:
+        if isinstance(exc, typer.Exit):
+            raise exc
+        if config.get_debug_mode(): 
+            print("[bold yellow][DEBUG MODE ACTIVE] Full stack trace below:[/bold yellow]\n")
+            raise exc
+        print(f"[bold red]Fatal Error:[/bold red] {str(exc)}")
+        print("[dim]Enable debug with 'glimpse config debug' for full diagnostic details.[/dim]")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    cli()

glimpsecli/utils.py

@@ -0,0 +1,130 @@
+from pathlib import Path
+import subprocess
+import re
+
+_GITHUB_URL_REGEX = re.compile(r'^(?:https:\/\/github\.com\/|git@github\.com:)[\w\-]+\/[\w\-]+(?:\.git)?$')
+_GITHUB_URL_OWNER_REPO = r"(?:https?://github\.com/|git@github\.com:)([\w-]+)/([\w-]+?)(?:\.git)?$"
+
+def _parse_github_owner_repo(url: str) -> tuple[str, str]:
+    """Gets owner and repository name from GitHub url.
+
+    [!] Requires valid GitHub url.
+
+    Args:
+        url: GitHub repository url.
+    
+    Returns:
+        Tuple of (owner, repository).
+    """
+    match = re.match(_GITHUB_URL_OWNER_REPO, url.strip())
+    assert match
+    owner, repo = match.groups()
+    return owner, repo
+
+# --- exported
+def get_git_remote_url() -> str | None:
+    """Get git remote repository url from git.
+
+    [!] Uses `git` command.
+
+    Returns:
+        Git remote repository url if was able to fetch it, else `None`.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+def is_valid_repo_url(url: str) -> bool:
+    """Validate repository URL.
+    
+    Valid URL will follow this pattern: 
+    - `https://github.com/user/repo.git`
+    - `git@github.com:user/repo.git`.
+
+    Args:
+        url: URL to validate.
+    
+    Returns:
+        True if URL is valid.
+
+    Notes:
+        This function checks only format. It does not verify
+        URL resource existence. 
+    """
+    return bool(_GITHUB_URL_REGEX.match(url))
+
+def create_alt_repo_url(url: str):
+    """Creates alternative GitHub repository url.
+
+    For https urls returns ssh url and the oposite way.
+    [!] Requires valid Github url.
+
+    Args:
+        url: Github repository url.
+
+    Returns:
+        Alternative GitHub repository url.
+    """
+    assert is_valid_repo_url(url)
+    owner, repo = _parse_github_owner_repo(url)
+    if url.startswith("https://"):
+        return f"git@github.com:{owner}/{repo}.git"
+    else:
+        return f"https://github.com/{owner}/{repo}.git"
+
+def generate_local_ssh_key() -> tuple[str, str]:
+    """Generates a temporary project-specific SSH key pair locally if it doesn't exist.
+    
+    Keys are generated in directory `.git/shared_repo_keys/` using rsa algorithm.
+    [!] Uses `ssh-keygen` command.
+
+    Returns:
+        Tuple of (private_key, public_key).
+    """
+    key_dir = Path(".git") / "shared_repo_keys"
+    key_dir.mkdir(parents=True, exist_ok=True)
+    private_key_path = key_dir / "id_rsa"
+    public_key_path = key_dir / "id_rsa.pub"
+    if not private_key_path.exists():
+        subprocess.run(
+            [
+                "ssh-keygen",
+                "-t",
+                "rsa",
+                "-N",
+                "",
+                "-f",
+                str(private_key_path),
+                "-C",
+                "git-glimpse-cli",
+            ],
+            check=True,
+            capture_output=True,
+        )
+    private_key = private_key_path.read_text()
+    public_key = public_key_path.read_text().strip()
+    return private_key, public_key
+
+def enrich_status(status: str) -> str:
+    """Adds color coding for build status codes.
+
+    Args:
+        status: Build status code.
+
+    Returns:
+        Color coded build status code.
+    """
+    match status:
+        case "pending": return "[bold blue]pending[/bold blue]"
+        case "success": return "[bold green]success[/bold green]"
+        case "failed": return "[bold red]failed[/bold red]"
+        case "violation": return "[bold magenta]violation[/bold magenta]"
+        case "running": return "[/bold cyan]running[/bold cyan]"
+        case _: return "[bold dim]?[/bold dim]"