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 set-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 set-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. |
octotrack config github-token-help |
An explanation on how to create a GitHub Authentication Token |
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 set-token, and is loaded as an environment variable at runtime.
License
MIT — see LICENSE for details.
Contributing
See Contributing.md for details.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file octotrack-0.2.0.tar.gz.
File metadata
- Download URL: octotrack-0.2.0.tar.gz
- Upload date:
- Size: 11.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c80a8975b65df866162f9394b11f78296d17e1b618e1e32ffbee9155cf762152
|
|
| MD5 |
463221f5ae4b88a6a3896a1fc289daa2
|
|
| BLAKE2b-256 |
98c7a2461b27234b9704e481319e1584847efb1075bea99f38c8a9bb88f4cec7
|
Provenance
The following attestation bundles were made for octotrack-0.2.0.tar.gz:
Publisher:
publish.yaml on JKG-cpu/OctoTrack
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
octotrack-0.2.0.tar.gz -
Subject digest:
c80a8975b65df866162f9394b11f78296d17e1b618e1e32ffbee9155cf762152 - Sigstore transparency entry: 2333482720
- Sigstore integration time:
-
Permalink:
JKG-cpu/OctoTrack@d1e5a76286e4d29519fea05d5baaf0e46a40287a -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/JKG-cpu
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yaml@d1e5a76286e4d29519fea05d5baaf0e46a40287a -
Trigger Event:
push
-
Statement type:
File details
Details for the file octotrack-0.2.0-py3-none-any.whl.
File metadata
- Download URL: octotrack-0.2.0-py3-none-any.whl
- Upload date:
- Size: 18.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d5a6ed1a89b0a2d18d86798e1d2064a048aa87ff8ab1cff64df1a2d3c9c5d70b
|
|
| MD5 |
d7e426110c3dbbd7b1639c1597ad28f6
|
|
| BLAKE2b-256 |
c58b38013681edcdd773e1d8230e5e8966ee4816f2706267f5dd73bb439ef225
|
Provenance
The following attestation bundles were made for octotrack-0.2.0-py3-none-any.whl:
Publisher:
publish.yaml on JKG-cpu/OctoTrack
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
octotrack-0.2.0-py3-none-any.whl -
Subject digest:
d5a6ed1a89b0a2d18d86798e1d2064a048aa87ff8ab1cff64df1a2d3c9c5d70b - Sigstore transparency entry: 2333482728
- Sigstore integration time:
-
Permalink:
JKG-cpu/OctoTrack@d1e5a76286e4d29519fea05d5baaf0e46a40287a -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/JKG-cpu
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yaml@d1e5a76286e4d29519fea05d5baaf0e46a40287a -
Trigger Event:
push
-
Statement type:
