corclient 1.1.0

Internal CLI tool for microservices management, infrastructure administration and monitoring with AWS Cognito authentication

CoreCLI

Internal CLI tool for microservices management, infrastructure administration and monitoring with AWS Cognito authentication.

Features

• 🔐 AWS Cognito Authentication - Secure authentication using PKCE (Proof Key for Code Exchange) flow
• 🚀 Microservices Management - Interact with internal microservices infrastructure
• 📊 Basic Monitoring - Monitor and manage microservices health
• 🔄 Token Management - Automatic token refresh and session handling
• 💻 CLI-First Design - Built with modern CLI best practices using Typer

Requirements

• Python 3.9 or higher
• AWS Cognito user pool configured with Hosted UI
• Valid AWS Cognito credentials

Installation

Via pip (Recommended)

pip install corclient

Via Homebrew (macOS/Linux)

# Add the tap
brew tap ProjectCORTeam/corcli https://github.com/ProjectCORTeam/corcli.git

# Install
brew install corclient

To update:

brew update && brew upgrade corclient

Development Installation

git clone https://github.com/ProjectCORTeam/corcli.git
cd corcli
pip install -e .

Quick Start

1. Login

Authenticate with AWS Cognito using the Hosted UI:

cor login

This will:

• Open your browser to the Cognito Hosted UI
• Start a local callback server
• Complete the PKCE flow
• Store tokens securely

Custom Redirect URI

If you need to redirect to a custom app scheme:

cor login --app-redirect myapp://callback

2. Check Authentication Status

View your current authentication details:

cor whoami

This displays:

• User information from the ID token
• Token expiration time
• Active session details

3. Refresh Tokens

Manually refresh your access tokens:

cor refresh

The CLI automatically refreshes tokens when needed, but you can manually trigger a refresh if required.

4. Logout

Clear local session and revoke tokens:

cor logout

This will:

• Revoke active tokens with Cognito
• Clear local token storage
• End your authentication session

5. Calling the GraphQL API (Amplify / AppSync)

After logging in, you can call the backend GraphQL API using the same session. Set the endpoint URL and use the graphql module from your code:

# Opcional: endpoint por defecto es https://api.cor-dev.com/graphql
export COR_GRAPHQL_URL="https://api.cor-dev.com/graphql"

From Python:

from corecli.graphql import graphql_request

# Ejemplo: listar equipos
result = graphql_request("""
  query ListTeams {
    listTeams {
      items { id name description }
    }
  }
""")
print(result["data"]["listTeams"]["items"])

The client sends your Cognito id_token in the Authorization: Bearer <token> header and refreshes it automatically if expired.

Configuration

CoreCLI requires the following environment variables or configuration:

# AWS Cognito Configuration
COGNITO_DOMAIN=your-domain.auth.region.amazoncognito.com
COGNITO_CLIENT_ID=your-client-id
COGNITO_REDIRECT_URI=http://localhost:8080/callback

# GraphQL API (Amplify/AppSync) - opcional; default https://api.cor-dev.com/graphql
COR_GRAPHQL_URL=https://api.cor-dev.com/graphql

Configuration can be set via:

• Environment variables
• Configuration file (.corecli/config)
• Command-line arguments

Usage Examples

Basic Authentication Flow

# Login to Cognito
cor login

# Check who is logged in
cor whoami

# When done, logout
cor logout

Using with Custom Applications

# Login and redirect to custom app
cor login --app-redirect myapp://authenticated

# The CLI will handle authentication and redirect to your app

Command Reference

Command	Description	Options
cor login	Authenticate with Cognito	--app-redirect, -r - Custom redirect URI
cor whoami	Show authenticated user info	None
cor refresh	Refresh authentication tokens	None
cor logout	End session and revoke tokens	None

Development

Setup Development Environment

# Clone repository
git clone https://github.com/ProjectCORTeam/corcli.git
cd corcli

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks (optional but recommended)
pip install pre-commit
pre-commit install

# Run the CLI
cor --help

Development Tools

The project uses modern Python development tools:

• Ruff - Fast Python linter (replaces flake8, isort, and more)
• Black - Code formatter
• MyPy - Static type checker
• Pre-commit - Git hooks for automated checks

Running Checks Locally

# Run linting
make lint

# Fix linting issues automatically
make lint-fix

# Format code
make format

# Check formatting (without modifying)
make format-check

# Run type checking
make type-check

# Build and verify package
make build

# Run all checks
make all

# Clean build artifacts
make clean

Or manually:

# Linting
ruff check corecli/

# Formatting
black corecli/

# Type checking
mypy corecli/

# Build
python -m build
twine check dist/*

Project Structure

corecli/
├── corecli/
│   ├── __init__.py      # Package initialization
│   ├── cli.py           # CLI commands and interface
│   ├── auth.py          # Authentication logic
│   ├── pkce.py          # PKCE flow implementation
│   └── utils.py         # Utility functions
├── pyproject.toml       # Project metadata
├── setup.py             # Package setup
└── README.md            # This file

Security Considerations

• PKCE Flow: Uses the industry-standard PKCE flow for secure OAuth 2.0 authentication
• Token Storage: Tokens are stored securely in the local user directory
• Automatic Refresh: Access tokens are automatically refreshed before expiration
• Session Management: Proper logout flow revokes tokens server-side

Troubleshooting

Authentication Fails

If authentication fails, check:

1. Cognito domain and client ID are correct
2. Redirect URI is whitelisted in Cognito
3. User pool has Hosted UI enabled
4. Network connectivity to Cognito endpoints

Token Refresh Issues

If token refresh fails:

1. Check that refresh token hasn't expired
2. Verify Cognito client settings allow refresh tokens
3. Try logging out and logging in again

Port Already in Use

If the callback server can't start:

# The default port (8080) might be in use
# Kill the process or configure a different port

Contributing

This is an internal tool for ProjectCOR Team. If you're a team member:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and ensure they pass all checks:

   make lint
   make format
   make type-check
   make build
   

4. Commit your changes using Conventional Commits:

   git commit -m 'feat: add amazing feature'
   git commit -m 'fix: resolve authentication issue'
   git commit -m 'docs: update README'
   

5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Quality Checks

All pull requests must pass:

• ✅ Ruff linting - Code quality and style checks
• ✅ Black formatting - Consistent code formatting
• ✅ MyPy type checking - Static type validation (warnings allowed)
• ✅ Package build - Successful package creation
• ✅ Twine validation - PyPI metadata verification

These checks run automatically on every release.

Versioning

We use Semantic Versioning via semantic-release. Versions are automatically generated based on commit messages following Conventional Commits.

Commit Message Format

• feat: - New feature (minor version bump)
• fix: - Bug fix (patch version bump)
• feat!: or BREAKING CHANGE: - Breaking change (major version bump)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For internal support:

• Report issues: GitHub Issues
• Documentation: GitHub Wiki
• Releases: GitHub Releases

Authors

• Carlos Ferrer - Initial work - ProjectCOR Team

---

Built with ❤️ by the ProjectCOR Team