itcpr 2.0.8

CLI tool for syncing GitHub repositories from ITCPR Cloud

ITCPR CLI

A production-ready CLI tool for syncing GitHub repositories from ITCPR Cloud to your local machine.

Features

• 🔐 Device-based authentication with ITCPR Cloud
• 📦 Automatic repository synchronization
• 🔄 Manual or continuous sync modes
• 💾 Local SQLite database for metadata tracking
• 🔒 Secure token storage using OS keyring
• 🛡️ Safe git operations with conflict detection

Installation

From PyPI (Recommended)

pip install itcpr
# OR
pip3 install itcpr
# OR
python3 -m pip install itcpr

From Source

If you want to install from source or contribute:

git clone <repository-url>
cd cloud-cli
pip install -e .
# OR
pip3 install -e .
# OR
python3 -m pip install -e .

Uninstall

To remove the CLI tool:

pip uninstall itcpr

Note: This will remove the CLI tool but will not delete:

• Configuration files (~/.itcpr/config.toml)
• Local repository database (~/.itcpr/repos.db)
• Stored device tokens (in OS keyring)

To completely remove all data:

# Uninstall the package
pip uninstall itcpr
# OR
pip3 uninstall itcpr
# OR
python3 -m pip uninstall itcpr

# Remove configuration and data
rm -rf ~/.itcpr

# Remove stored tokens (OS keyring)
# On macOS: Use Keychain Access app to remove "itcpr" entries
# On Linux: Use your keyring manager (e.g., seahorse, kwallet)
# On Windows: Use Credential Manager

Requirements

• Python 3.10+
• Git (system installation)
• Access to api.itcpr.org (API) and cloud.itcpr.org (frontend)

Quick Start

1. Login

Authenticate your device with ITCPR Cloud:

itcpr login

This will:

• Open your browser to the device login page
• Display a device code
• Wait for approval
• Store credentials securely

2. Check Status

View your assigned repositories:

itcpr status

3. List Repositories

See all repositories assigned to your device:

itcpr repos

4. Clone a Repository

Clone a repository to your local machine:

itcpr clone paperport-itcpr

Or specify a custom path:

itcpr clone paperport-itcpr --path ~/projects/paperport

5. Sync Repositories

Sync all cloned repositories:

itcpr sync

Run continuous sync (watches for changes):

itcpr sync --watch

With custom interval:

itcpr sync --watch --interval 120  # Sync every 2 minutes

6. Logout

Clear stored credentials:

itcpr logout

Commands

itcpr login

Starts device authentication flow. Opens browser to cloud.itcpr.org/device and polls the API at api.itcpr.org for approval.

itcpr logout

Revokes device token and clears local metadata.

itcpr status

Shows:

• Logged-in user information
• Device ID
• Assigned repositories
• Local repositories with sync status

itcpr repos

Lists all repositories assigned to this device with their clone status.

itcpr clone <repo>

Clones a repository from GitHub using short-lived installation tokens.

Options:

• --path, -p: Custom local path for the repository

itcpr sync

One-shot synchronization of all cloned repositories.

Options:

• --watch, -w: Run continuous sync loop
• --interval, -i: Sync interval in seconds (watch mode only, default: 60)

Sync Rules (itcpr.yml):

You can configure per-repository sync behavior by creating an itcpr.yml file in the repository root:

sync:
  enabled: true          # Enable/disable sync for this repo (default: true)
  auto_commit: true      # Auto-commit local changes (default: true)
  auto_push: true        # Auto-push local commits (default: true)
  branch: main           # Optional: specific branch to sync
  ignore:               # Optional: patterns to ignore
    - "*.log"
    - "temp/"

Note: To use itcpr.yml, install PyYAML: pip install itcpr[yaml] or pip install PyYAML

How It Works

Authentication

1. Device requests authentication code from backend
2. User approves device in browser at cloud.itcpr.org/device
3. Device token is stored securely in OS keyring
4. Token is used for all API requests

Repository Sync

1. Fetches latest changes from remote
2. Detects uncommitted local changes
3. Commits local changes if any
4. Pulls remote changes with rebase
5. Pushes local commits if permitted
6. Aborts on merge conflicts (requires manual resolution)

Security

• No Personal Access Tokens: Only uses backend-issued short-lived GitHub installation tokens
• Device Tokens: Revocable device authentication
• OS Keyring: Credentials stored securely using system keyring
• Safe Git Operations: Never force-pushes, detects conflicts

Configuration

Global Configuration

Configuration is stored in ~/.itcpr/config.toml.

Repository metadata is stored in ~/.itcpr/repos.db (SQLite).

Per-Repository Configuration (itcpr.yml)

Each repository can have its own itcpr.yml file in the repository root to control sync behavior:

sync:
  enabled: true          # Enable/disable sync for this repo
  auto_commit: true      # Automatically commit local changes
  auto_push: true        # Automatically push local commits
  branch: main           # Optional: sync specific branch
  ignore: []             # Optional: file patterns to ignore

Example: Disable auto-push for a repository

sync:
  auto_push: false

Example: Disable sync entirely for a repository

sync:
  enabled: false

Installation: To use itcpr.yml files, install the optional YAML dependency:

pip install itcpr[yaml]
# OR
pip install PyYAML

Development / Mock Mode

When the API at api.itcpr.org is unavailable, the CLI automatically falls back to mock API responses for testing and development.

Automatic Mock Mode:

• If the backend returns 404 or is unreachable, mock responses are used automatically
• You'll see a warning: "⚠️ Backend unavailable, using mock mode for testing"

Manual Mock Mode: You can also enable mock mode explicitly:

# Using environment variable
export ITCPR_MOCK_MODE=true
itcpr login

# Or set in config file (~/.itcpr/config.toml)
# mock_mode = true

Mock Features:

• Auto-approves device login after 2 seconds
• Provides sample user and repository data
• Generates mock GitHub tokens
• All commands work in mock mode for testing

Troubleshooting

"Not logged in" error

Run itcpr login to authenticate your device. If the backend is unavailable, mock mode will activate automatically.

"Repository not assigned" error

The repository must be assigned to your device in ITCPR Cloud. Contact an administrator.

Merge conflicts

If a merge conflict is detected during sync:

1. Resolve conflicts manually in the repository
2. Commit the resolution
3. Run itcpr sync again

Git command not found

Ensure Git is installed and available in your PATH:

git --version

Token storage issues

On Linux, you may need to install a keyring backend:

# For GNOME
sudo apt-get install python3-keyring

# For KDE
sudo apt-get install python3-keyring kdewallet

Development

Project Structure

cloud-cli/
├── itcpr/
│   ├── __init__.py      # Package initialization
│   ├── cli.py           # CLI commands
│   ├── auth.py          # Authentication
│   ├── api.py           # API client
│   ├── gitops.py        # Git operations
│   ├── sync.py          # Sync logic
│   ├── config.py        # Configuration
│   ├── storage.py       # SQLite storage
│   └── utils.py         # Utilities
├── setup.py             # Setup script
├── pyproject.toml       # Project metadata
└── README.md            # This file

Running Tests

# Install in development mode
pip install -e .
# OR
pip3 install -e .
# OR
python3 -m pip install -e .

# Run CLI
itcpr --help

API Endpoints

The CLI communicates with these backend endpoints:

• POST /api/device/start - Start device authentication
• GET /api/device/poll - Poll for authentication approval
• POST /api/device/revoke - Revoke device token
• GET /api/agent/me - Get device/user information
• GET /api/agent/repos - Get assigned repositories
• POST /api/agent/token - Get GitHub installation token

License

MIT License

Support

For issues and questions, contact ITCPR support or open an issue on GitHub.