Installation

argo-rs is available for macOS and Linux. Choose the installation method that works best for you.

Requirements

• Git repository with GitHub remote
• macOS or Linux
• For AI features: Gemini API key

Supported Platforms

Pre-built binaries are available for:

For other platforms (macOS Intel, Linux ARM64), please build from source.

Installation Methods

• Quick Install - Recommended for most users
• Build from Source - For contributors or unsupported platforms

Quick Install

The easiest way to install argo-rs on macOS or Linux.

One-Line Install

curl -sSL https://raw.githubusercontent.com/stefanodecillis/argo-rs/main/install.sh | bash

This will:

1. Detect your platform (macOS/Linux, x86_64/aarch64)
2. Download the latest release from GitHub
3. Install argo to ~/.local/bin/
4. Sign the binary on macOS for Keychain compatibility

Verify Installation

After installation, verify it works:

argo --version

If the command is not found, ensure ~/.local/bin is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Then reload your shell:

source ~/.bashrc  # or source ~/.zshrc

Next Steps

1. Authenticate with GitHub
2. Navigate to a git repository and run argo to launch the TUI

Build from Source

Build argo-rs from source for contributors or unsupported platforms.

Prerequisites

• Rust 1.70 or later
• Git

Build Steps

# Clone the repository
git clone https://github.com/stefanodecillis/argo-rs.git
cd argo-rs

# Build release binary (optimized)
cargo build --release

# The binary is at target/release/argo

Install to PATH

Copy the binary to a location in your PATH:

# Create ~/.local/bin if it doesn't exist
mkdir -p ~/.local/bin

# Copy the binary
cp target/release/argo ~/.local/bin/

Ensure ~/.local/bin is in your PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Development Build

For development with faster compile times (but slower runtime):

cargo build
cargo run -- --help

Running Tests

cargo test

Code Quality

# Format code
cargo fmt

# Lint
cargo clippy

Updating

Keep argo-rs up to date with the latest features and fixes.

Quick Update

Run the install script again to update to the latest version:

curl -sSL https://raw.githubusercontent.com/stefanodecillis/argo-rs/main/install.sh | bash

The script will:

1. Download the latest release
2. Replace the existing binary
3. Preserve your configuration and credentials

Check Current Version

argo --version

Update from Source

If you built from source:

cd argo-rs
git pull origin main
cargo build --release
cp target/release/argo ~/.local/bin/

Uninstalling

Remove argo-rs from your system.

Quick Uninstall

curl -sSL https://raw.githubusercontent.com/stefanodecillis/argo-rs/main/uninstall.sh | bash

This will:

• Remove the argo binary
• Optionally remove configuration files
• Provide instructions for removing stored credentials

Manual Uninstall

Remove Binary

rm -f ~/.local/bin/argo

Remove Configuration

macOS:

rm -rf ~/Library/Application\ Support/com.argo-rs.argo-rs

Linux:

rm -rf ~/.config/argo-rs

Remove Credentials

Credentials are stored securely in your system keychain:

• macOS: Open Keychain Access and search for “argo-rs”
• Linux: Use your Secret Service manager (GNOME Keyring, KWallet, etc.) to find and remove “argo-rs” entries

The uninstall script cannot automatically remove keychain entries for security reasons.

CLI Reference

argo-rs provides a comprehensive command-line interface for GitHub repository management.

Command Structure

argo [COMMAND] [OPTIONS]

Running argo without arguments launches the TUI mode.

Available Commands

Global Options

argo --help     # Show help
argo --version  # Show version

Quick Examples

# Authenticate
argo auth login

# List PRs
argo pr list

# Create commit with AI-generated message
argo commit -a --ai

# Launch TUI
argo

Authentication

argo-rs uses GitHub’s OAuth Device Flow for secure browser-based authentication.

Commands

Login

argo auth login

This will:

1. Display a device code
2. Open your browser to GitHub’s authorization page
3. Wait for you to enter the code and authorize
4. Securely store the token in your system keychain

Logout

argo auth logout

Removes stored GitHub credentials from the keychain.

Check Status

argo auth status

Shows whether you’re currently authenticated and displays your GitHub username.

How OAuth Device Flow Works

1. argo-rs requests a device code from GitHub
2. You visit https://github.com/login/device and enter the code
3. GitHub authenticates you and grants access to argo-rs
4. The token is stored securely in your system keychain

This flow is more secure than storing personal access tokens because:

• No token is ever displayed or copied
• Tokens have limited, well-defined scopes
• Authorization can be revoked from GitHub settings

Token Storage

Tokens are stored securely using your system’s native credential storage:

• macOS: Keychain
• Linux: Secret Service (GNOME Keyring, KWallet, etc.)

See Credential Storage for details.

Troubleshooting

“Not authenticated” Error

Run argo auth login to authenticate.

Token Expired

Re-run argo auth login. The old token will be replaced.

Browser Doesn’t Open

Manually visit https://github.com/login/device and enter the displayed code.

Pull Requests

Manage GitHub pull requests from the command line.

List Pull Requests

# List open PRs (default)
argo pr list

# List all PRs (open, closed, merged)
argo pr list --state=all

# List closed PRs only
argo pr list --state=closed

# Filter by author
argo pr list --author=username

Create Pull Request

# Create with title only
argo pr create --title "Add new feature"

# Create with title and body
argo pr create --title "Add new feature" --body "Description of changes"

# Create as draft
argo pr create --title "WIP: Feature" --draft

# Create with AI-generated title and body
argo pr create --ai

The --ai flag uses Gemini AI to analyze your commits and generate an appropriate title and description. Requires a Gemini API key.

View Pull Request

# View PR details and comments
argo pr view 123

Displays:

• PR title and description
• Status (open, merged, closed)
• Author and reviewers
• Comments and review comments

Comment on Pull Request

argo pr comment 123 "Looks good! Just one suggestion..."

Merge Pull Request

# Merge commit (default)
argo pr merge 123

# Squash and merge
argo pr merge 123 --squash

# Rebase and merge
argo pr merge 123 --rebase

# Delete branch after merge
argo pr merge 123 --delete

Merge Strategies

Branches

Manage remote branches on GitHub.

List Branches

argo branch list

Lists all remote branches in the repository.

Delete Branch

# Delete with confirmation prompt
argo branch delete feature-branch

# Delete without confirmation
argo branch delete old-branch --force

Note: This deletes the remote branch on GitHub. Local branches are not affected.

Common Workflows

Clean Up Merged Branches

After merging a PR, delete the feature branch:

# Merge the PR with branch deletion
argo pr merge 123 --delete

# Or delete separately
argo branch delete feature-branch

Remove Stale Branches

List branches to identify old ones, then delete:

argo branch list
argo branch delete stale-feature --force

Commits

Create commits with optional AI-generated messages.

Basic Usage

# Commit staged changes
argo commit -m "feat: add user authentication"

# Stage all changes and commit
argo commit -a -m "fix: resolve login bug"

AI-Generated Messages

Let Gemini AI analyze your changes and generate a commit message:

# Generate message for staged changes
argo commit --ai

# Stage all and generate message
argo commit -a --ai

The AI will:

1. Analyze your staged changes (diff)
2. Generate a conventional commit message
3. Show you the message for confirmation

Requires a Gemini API key.

Options

Commit Message Format

argo-rs follows Conventional Commits:

type(scope): description

[optional body]

Common types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• refactor: Code refactoring
• test: Adding tests
• chore: Maintenance tasks

Configuration Commands

Manage argo-rs settings from the command line.

Gemini API Key

Required for AI-powered features (commit messages, PR descriptions).

# Set your API key
argo config set gemini-key YOUR_API_KEY

# Check if key is configured
argo config get gemini-key

Get an API key from Google AI Studio.

Gemini Model

Choose which Gemini model to use for AI features.

# Set the model
argo config set gemini-model gemini-2.5-flash

# Check current model
argo config get gemini-model

Available Models

Configuration Storage

Settings are stored in:

• macOS: ~/Library/Application Support/com.argo-rs.argo-rs/config.toml
• Linux: ~/.config/argo-rs/config.toml

See File Locations for details.

TUI Guide

argo-rs includes an interactive Terminal User Interface (TUI) for managing GitHub repositories visually.

Launching the TUI

Navigate to a git repository with a GitHub remote and run:

argo

The TUI provides:

• Visual navigation of pull requests
• Real-time polling for PR updates
• Keyboard-driven workflow with vim-style navigation
• Quick access to all argo-rs features

Screens

The TUI consists of multiple screens:

Requirements

• Terminal with at least 80x24 characters
• GitHub authentication (run argo auth login first)
• Valid git repository with GitHub remote

Next Steps

• Learn Navigation & Keybindings
• Or use the CLI for scripting

Navigation & Keybindings

argo-rs uses vim-style navigation for efficient keyboard-driven workflows.

Global Keybindings

Navigation

Screen Navigation

PR List Actions

Tips

• Circular Navigation: Lists wrap around - pressing j at the bottom goes to the top
• Escape Anywhere: Press Esc or q to go back or quit from any screen
• Quick Refresh: Press r to refresh data without leaving the current view

Configuration

argo-rs stores configuration and credentials securely on your system.

Configuration Files

Settings are stored in TOML format:

• macOS: ~/Library/Application Support/com.argo-rs.argo-rs/config.toml
• Linux: ~/.config/argo-rs/config.toml

Credentials

Sensitive data (tokens, API keys) are stored in your system keychain:

• macOS: Keychain
• Linux: Secret Service (GNOME Keyring, KWallet, etc.)

Available Settings

Sections

• File Locations - Where config files are stored
• Credential Storage - How secrets are protected
• AI Setup - Configure Gemini integration

File Locations

argo-rs follows platform conventions for configuration storage.

Configuration Directory

Configuration File

The main configuration file is config.toml inside the configuration directory.

macOS:

~/Library/Application Support/com.argo-rs.argo-rs/config.toml

Linux:

~/.config/argo-rs/config.toml

Config File Format

# Example config.toml
gemini_model = "gemini-2.5-flash"

Credentials

Credentials are not stored in the config file. They are stored securely in your system keychain. See Credential Storage.

Resetting Configuration

To reset configuration, delete the config directory:

macOS:

rm -rf ~/Library/Application\ Support/com.argo-rs.argo-rs

Linux:

rm -rf ~/.config/argo-rs

Note: This does not remove credentials from the keychain. Use argo auth logout to remove GitHub credentials.

Credential Storage

argo-rs stores sensitive credentials securely using your system’s native keychain.

Storage Mechanism

What’s Stored

Security Features

Secret Handling

argo-rs uses the secrecy crate to prevent accidental token exposure:

• Tokens are wrapped in SecretString
• Debug output redacts sensitive values
• Memory is zeroed when tokens are dropped

Three-Tier Fallback

Credentials are retrieved in order:

1. Environment Variables - GITHUB_TOKEN, GEMINI_API_KEY
2. In-Memory Cache - For performance during a session
3. System Keychain - Persistent secure storage

This allows CI/CD environments to use environment variables while desktop users benefit from keychain storage.

Managing Credentials

GitHub Token

# Login (stores token in keychain)
argo auth login

# Logout (removes token from keychain)
argo auth logout

# Check status
argo auth status

Gemini API Key

# Set key (stores in keychain)
argo config set gemini-key YOUR_KEY

# Check if configured
argo config get gemini-key

Environment Variables

For CI/CD or if you prefer not to use the keychain:

export GITHUB_TOKEN="ghp_xxxxx"
export GEMINI_API_KEY="xxxxx"

These take precedence over keychain-stored credentials.

AI Setup (Gemini)

argo-rs integrates with Google’s Gemini AI for generating commit messages and PR descriptions.

Getting an API Key

1. Visit Google AI Studio
2. Sign in with your Google account
3. Create a new API key
4. Copy the key

Configuring argo-rs

# Set your API key
argo config set gemini-key YOUR_API_KEY

# Verify it's configured
argo config get gemini-key

Selecting a Model

Choose which Gemini model to use:

# Set the model
argo config set gemini-model gemini-2.5-flash

# Check current model
argo config get gemini-model

Available Models

Using AI Features

AI Commit Messages

Generate a commit message from your staged changes:

# Stage files first
git add .

# Generate and commit
argo commit --ai

# Or stage all and generate
argo commit -a --ai

AI PR Descriptions

Generate a PR title and description from your branch commits:

argo pr create --ai

How It Works

1. argo-rs analyzes your changes (diff for commits, commits for PRs)
2. Sends context to Gemini API
3. Returns a formatted message following conventional commit style
4. Shows you the result for confirmation before applying

Troubleshooting

“API key not configured”

Run argo config set gemini-key YOUR_KEY with your API key.

“Rate limit exceeded”

Wait a moment and try again. Free tier has usage limits.

Poor quality suggestions

Try a different model with argo config set gemini-model gemini-3-flash-preview.

Development

Guide for contributing to argo-rs.

Setup

# Clone the repository
git clone https://github.com/stefanodecillis/argo-rs.git
cd argo-rs

# Build
cargo build

# Run
cargo run -- --help

# Test
cargo test

# Format
cargo fmt

# Lint
cargo clippy

Architecture

src/
├── main.rs          # Entry point, CLI dispatch
├── error.rs         # Unified error handling
├── core/            # Business logic
│   ├── config.rs    # TOML config management
│   ├── credentials.rs # Credential storage
│   ├── git.rs       # Git operations
│   └── repository.rs # GitHub URL parsing
├── github/          # GitHub API
│   ├── client.rs    # Octocrab wrapper
│   ├── auth.rs      # OAuth Device Flow
│   ├── pull_request.rs
│   └── branch.rs
├── cli/             # Command handlers
├── tui/             # Terminal UI
│   ├── app.rs       # State machine
│   ├── event.rs     # Input handling
│   └── screens/     # Screen implementations
└── ai/              # Gemini integration
    ├── gemini.rs    # API client
    └── prompts.rs   # Prompt templates

Key Patterns

Error Handling

All errors flow through GhrustError in src/error.rs:

#![allow(unused)]
fn main() {
pub enum GhrustError {
    Git(String),
    GitHub(String),
    Config(String),
    // ...
}
}

Credential Management

Three-tier fallback: environment → cache → keyring. Uses secrecy::SecretString to prevent accidental exposure.

Async Architecture

Tokio runtime with channel-based message passing between TUI and async operations.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run cargo fmt and cargo clippy
5. Run cargo test
6. Submit a pull request

License

MIT - see LICENSE for details.