OctoTrack

An async CLI client for GitHub, built to track commits, pull requests, issues, releases, and general repository activity — straight from your terminal.

OctoTrack talks directly to the GitHub REST API using httpx, so there's no dependency on the gh CLI or any GitHub SDK.

Table of Contents

Installation

Install via pip:

pip install octotrack

Requires Python 3.13+.

Quick Start

# One-time setup: creates config/data directories
octotrack setup

# Add a GitHub personal access token
octotrack config edit-token

# Set a default repo so you don't have to type it every time
octotrack repo default JKG-cpu/OctoTrack

# Pull general info on a repo
octotrack repo info

Commands

All commands are grouped under three top-level subcommands: setup, config, and repo. Run octotrack --help, or --help on any subcommand, to see this reference from the CLI itself.

setup

Manages the local files OctoTrack needs to run (config directory, data directory, and env file for your token).

Command Description
octotrack setup Creates the config and data directories, and the settings file, if they don't already exist. Safe to run again — existing valid setups are left untouched.
octotrack setup validate Checks that all required paths exist and reports whether a GitHub token is set.
octotrack setup remove Deletes all data and config files created by OctoTrack, after a confirmation prompt.

config

Reads and writes local configuration, including your GitHub token.

Command Description
octotrack config show Prints all current config values.
octotrack config edit-token Prompts for a GitHub token and stores it as a local environment variable. Never written to the config file.
octotrack config set <key> <value> Sets a config value directly. Valid keys: default_owner, default_repo, default_pr_state, api_base_url.
octotrack config clear [--key/-k <key>] Resets a single config key to its default. Omit --key to reset the entire config.
octotrack config path Prints the path to the config settings file.

repo

Fetches and displays information about a GitHub repository.

Command Description
octotrack repo info [owner/repo] Shows general repository info: description, language, visibility, stars, forks, license, and README preview.
octotrack repo default <owner/repo> Sets a default owner and/or repo, used whenever owner/repo is omitted from other repo commands.
octotrack repo readme [owner/repo] Fetches and renders just the repository's README.
octotrack repo contents [owner/repo] [options] Lists the contents of a repository.

repo contents options:

Flag Description
-p, --path <path> List contents of a specific folder in the repository.
-h, --hidden Include hidden files (dotfiles) in the listing.
-l, --list Print as a flat list instead of a tree.
--depth <int> How many levels deep to recurse into subdirectories (default: 3).

Every repo command that accepts owner/repo will fall back to your configured default (set via octotrack repo default) for whichever part — owner, repo, or both — you omit.

Configuration

OctoTrack stores its config in an OS-appropriate location via platformdirs. Run octotrack config path to see the exact file on your system.

Your GitHub token is never stored in the config file — it lives exclusively in a local .env file managed by octotrack config edit-token, and is loaded as an environment variable at runtime.

License

MIT — see LICENSE for details.

Contributing

See Contributing.md for details.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for JKG from gravatar.com JKG

Credits

Author: JKG-cpu

Requires

Python >=3.13

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

octotrack-0.1.0.tar.gz (11.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

octotrack-0.1.0-py3-none-any.whl (17.2 kB view details)

Uploaded Python 3

File details

Details for the file octotrack-0.1.0.tar.gz.

File metadata

  • Download URL: octotrack-0.1.0.tar.gz
  • Upload date:
  • Size: 11.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for octotrack-0.1.0.tar.gz
Algorithm Hash digest
SHA256 8e39ed8d63445665f57a2b0aceb463f7f7204ebf0c725a61acf4233242e449e7
MD5 964283ac0a242f29f99130004067729c
BLAKE2b-256 66328d91df2cb899b031cfad4c22587c9c570009587b975d5ec73f29a91212d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for octotrack-0.1.0.tar.gz:

Publisher: publish.yaml on JKG-cpu/OctoTrack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file octotrack-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: octotrack-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 17.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for octotrack-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5070e891116771eca0ea38b92c26d4ac192a9ab6fc86295bf7af6688e74d7674
MD5 090ae87f46b685de8f848d1bc10c6f9e
BLAKE2b-256 d9c9deee3ee7e9da9c04ed76c290329271b9ca25b1b75664ca44f9719d2bc903

See more details on using hashes here.

Provenance

The following attestation bundles were made for octotrack-0.1.0-py3-none-any.whl:

Publisher: publish.yaml on JKG-cpu/OctoTrack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page