Metadata-Version: 2.4
Name: gl-connectors-cli
Version: 0.1.0
Author-email: GL Connectors Team <bosa-eng@gdplabs.id>
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests<3.0.0,>=2.31.0
Requires-Dist: pydantic<3.0.0,>=2.11.7
Provides-Extra: dev
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: ruff>=0.12.7; extra == "dev"
Requires-Dist: mypy>=1.17.0; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: pip-tools>=7.0.0; extra == "dev"

# GL Connectors CLI

A command-line interface for managing GL Connectors integrations and authentication.

## Prerequisites

<details>
<summary>Prerequisites details</summary>

1. **Python v3.11 or above** (to run `python`)

   - Using Conda (recommended):
     You can use [Miniconda](https://docs.anaconda.com/miniconda/install) to install and manage Python versions.

2. **Connector access** (contact your administrator for credentials)
</details>

## Installation

Install the CLI using:

```bash
pip install gl-connectors-cli
```

## Quick Start

Get up and create your first integration using GL Connectors CLI:

1. **Login**:

   ```bash
   glcon auth login
   # Make sure you have access to GL Connectors playground environment.
   # You will be prompted to enter:

   # Client API Key: sk-client-...
   # Username (User Identifier): your user identifier
   # User Secret: sk-user-...
   ```

2. **View Available Integrations**:

   ```bash
   glcon integrations
   ```

   You should have 0 integration(s) count for each connector listed.

3. **Add Your First Integration**:

   ```bash
   glcon integrations add github
   ```

   You should see the following message:

   ```
   ✓ OAuth flow initiated for github!
   Please visit the following URL to complete the integration:
   https://github.com/login/oauth/authorize?client_id=...
   ```

   Open the URL in your browser and follow the OAuth flow.

4. **Check your GitHub accounts**:

   After you have completed the OAuth flow, you can check your GitHub accounts.

   ```bash
   glcon integrations show github
   ```

   Voila! You should see your GitHub accounts listed, as shown below:

   ```
   Integrations for github
   =======================
   ℹ Found 1 integration(s)

   User Identifier | Status
   ------------------------------------
   | your-github-username | ✓ Selected
   ```

That's it! You're now ready to manage your GL Connectors' integrations.

## Command Reference

### Authentication Commands

| Command             | Description                          | Options           |
| ------------------- | ------------------------------------ | ----------------- |
| `glcon auth login`  | Authenticate with client credentials | `--api-url <url>` |
| `glcon auth status` | Check current authentication status  | -                 |
| `glcon auth logout` | Clear stored credentials             | -                 |

**Login prompts**:

- **Client API Key**: Your client API key (input hidden)
- **Username**: Your user identifier
- **User Secret**: Your user secret (input hidden)

**Configuration Options**:

- `--api-url`: Custom Connector URL (for development purposes)

### Integration Commands

| Command                                              | Description                                | Parameter(s)                                                       |
| ---------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
| `glcon integrations`                                 | List all connectors and integration counts | -                                                                  |
| `glcon integrations list`                            | Same as above (explicit)                   | -                                                                  |
| `glcon integrations add <connector>`                 | Add new integration via OAuth flow         | `<connector>`: github, google, etc.                                |
| `glcon integrations show <connector>`                | Show all accounts for a connector          | `<connector>`: github, google, etc.                                |
| `glcon integrations show <connector> <identifier>`   | Show specific integration details          | `<connector>`: github, google, etc. `<identifier>`: email/username |
| `glcon integrations remove <connector> <identifier>` | Remove specific integration                | `<connector>`: github, google, etc. `<identifier>`: email/username |
| `glcon integrations select <connector> <identifier>` | Set integration as primary                 | `<connector>`: github, google, etc. `<identifier>`: email/username |

**Examples**:

```bash
glcon integrations                           # List all connectors
glcon integrations add github                # Add GitHub integration
glcon integrations show google               # Show all Google accounts
glcon integrations show google user@gmail.com  # Show specific account details
glcon integrations remove github username    # Remove GitHub integration
glcon integrations select google user@gmail.com # Set as primary Google account
```

### User Commands

| Command                           | Description               | Parameter(s)                   |
| --------------------------------- | ------------------------- | ------------------------------ |
| `glcon users create <identifier>` | Create a new user account | `<identifier>`: email/username |

**Example**:

```bash
glcon users create john.doe@example.com
```

**Important**: Save the user secret securely! It's only shown once.

## Configuration

The CLI stores configuration in `~/.connector/config.json`. This file contains:

- Authentication session (client key, user token, API URL)
- Session expiration information

The API URL is only configurable during authentication using the `--api-url` flag.

## Getting Help

Get help for any command:

```bash
glcon --help                    # Main help
glcon auth --help              # Authentication commands help
glcon integrations --help      # Integration commands help
glcon users --help             # User management commands help
```

## Available Connectors

The available connectors depend on your Connector configuration. Common connectors include:

- **github**: GitHub API integration
- **google**: Google services integration
- **google_drive**: Google Drive integration
- **google_docs**: Google Docs integration
- **google_mail**: Google Mail integration

## Contributing

We welcome contributions! Please see our documentation:

- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Development setup, workflow, and code review guidelines
- **[constitution.md](constitution.md)** - Code generation standards

## License

This project is maintained by the GL Connectors Team.
