Recon CLI

Recon is a powerful CLI companion for developers and tools for agents, turning GitHub activity and repository data into useful insights from your terminal.

Overview

Recon allows developers to view basic GitHub analytics in the terminal quickly, rather than opening up their browser. This means it allows agents to interact with the service without having browser capabilities.

It is powered by Typer, a library for building fast CLI tools, and made pretty by Rich and its prebuilt components.

Features

• GitHub Authentication — Securely authenticate with GitHub using OAuth device flow.
• User Information — View information about your authenticated GitHub account.
• Repository Explorer — List and inspect GitHub repositories directly from the terminal.
• Repository Statistics — Explore repository languages, contributors, and other useful statistics.
• Rich Terminal UI — Clean, structured terminal output powered by Rich.
• Fast CLI Workflow — Quickly access GitHub information without leaving the command line.
• Modular Architecture — Built with reusable services and components to make Recon easy to maintain and extend.
• Automated Testing — Tested with an automated CI pipeline to help maintain reliability and code quality.

Installation

Since we want you to be able to use Recon from anywhere - not just one directory - we recommend you install it with uv package manager.

  uv tool install recon-github

For the best experience, then login to your GitHub account (this step is not strictly required).

  recon login

Usage

Here you can learn how to get started with terminal commands, and learn how to find more.

View Your GitHub Profile

The me command displays information about your authenticated GitHub account.

recon me

Example output:

╭────── Owen Palfreyman ───────╮ ╭──────────────────────────────╮
│ Repositories  2              │ │                              │
│ Followers     7              │ │                              │
│ Following     2                │ │                              │
│ Location      United Kingdom │ │                              │
│ Company       —              │ │                              │
│ Joined        2023-11-02     │ │                              │
╰───── @owenpalfreymandev ─────╯ │                              │
                                 ╰──────────────────────────────╯

Scout Another GitHub User

Use scout to explore another GitHub user's profile.

recon scout torvalds

Example output:

╭──────── Linus Torvalds ────────╮ ╭──────────────────────────────╮
│ Repositories  12               │ │                              │
│ Followers     318572           │ │                              │
│ Following     0                │ │                              │
│ Location      Portland, OR     │ │                              │
│ Company       Linux Foundation │ │                              │
│ Joined        2011-09-03       │ │                              │
╰────────── @torvalds ───────────╯ │                              │
                                   ╰──────────────────────────────╯

List Your Repositories

The list command displays your GitHub repositories.

recon list

This provides a quick way to see your repositories before using details to explore a specific project.

Authentication

Recon uses GitHub's device flow for authentication.

To log in:

recon login

To log out:

recon logout

Explore a Repository

The details command gives you an overview of a GitHub repository.

recon details owenpalfreymandev fpark

The command takes two arguments:

• owner — The GitHub username or organisation that owns the repository.
• repo — The name of the repository.

Need Some Help?

Not sure what a command can do? Recon has built-in help for every command.

recon details --help

This shows you the available arguments and options for the command, including additional ways to get information from a repository.

Usage: recon details [OPTIONS] {owner} {repo}

Gain insights into your repo

Arguments:
  owner    Repository owner, e.g. owenpalfreymandev
  repo     Repository name, e.g. reconcli

Options:
  --contributors    View contributors in more detail.
  --languages       View language usage in more detail.
  --help            Show this message and exit.

For example, the --languages option can be used to get a more detailed breakdown of the languages used in a repository:

recon details owenpalfreymandev fpark --languages

╭──────────────────────────────────────────────────────────╮
│                        LANGUAGES                         │
│                 owenpalfreymandev/fpark                  │
╰──────────────────────────────────────────────────────────╯
4 languages returned by GitHub · 100% of reported code

LANGUAGE BREAKDOWN
──────────────────────────────────────────────────────────
1    TypeScript                        279.9 KB
    ████████████████████████████████  95.9%

2    PLpgSQL                             7.0 KB
    █                                 2.4%

3    CSS                                 4.3 KB
    █                                 1.5%

4    JavaScript                           559 B
    █                                 0.2%
──────────────────────────────────────────────────────────
Showing all 4 languages

Explore Further

These are just some of the commands available in Recon. There are plenty more options to play with, with more commands and features coming soon. Check the roadmap for more details.

Contributing

Contributions are always welcome!

To clone the repo and download all dependencies, run:

git clone https://github.com/owenpalfreymandev/reconcli.git
uv sync

You can run unit tests and type tests with:

uv run pytest
uv run pyright

Be sure to lint before committing, or it will fail CI/CD:

uv run ruff check --fix .

Workflow

A basic workflow to follow is:

1. Fork the repository
2. Create a branch
3. Make changes
4. Run tests/lint/type checks
5. Open a PR

License

Recon is licensed under the MIT License. See the LICENSE file for details.

Author

Recon is developed by Owen Palfreyman.

GitHub: @owenpalfreymandev Repository: owenpalfreymandev/reconcli

or could just run recon details owenpalfreymandev reconcli --contributors wink wink