# cogops

`cogops` is a command-line tool for performing batch operations on AWS Cognito user pools.\
It supports synchronizing users into a local file, adding users to groups, and removing users from groups.

This project is designed to be simple, predictable, and operational-friendly.

---

## Requirements

- Rust toolchain (Rust 1.75 or newer recommended)
- AWS credentials with Administrator privileges for the target Cognito user pool
- Access to the AWS API (environment variables, credential file, or IAM role)

To install Rust:

```
curl https://sh.rustup.rs -sSf | sh
```

Verify installation:

```
rustc --version
cargo --version
```

---

## Building

Clone the repository and build the binary:

```
git clone https://github.com/ijanc/cogops.git
cd cogops
cargo build --release
```

The binary will be located at:

```
target/release/cogops
```

You can add it to your PATH or move it to `/usr/local/bin`.

---

## AWS Credentials

`cogops` uses the official AWS Rust SDK and respects all standard credential providers.

For example:

```
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1
```

---

## Commands Overview

`cogops` provides three main operations:

1. `sync`\
   Export all users of a Cognito User Pool into a local CSV file containing:\
   `username,email`.

2. `add`\
   Add users (specified by email) to one or more Cognito groups.

3. `del`\
   Remove users from one or more Cognito groups.

---

## 1. Synchronizing users (sync)

This operation reads all users from the provided Cognito User Pool ID and writes them to a CSV file.

Example:

```
cogops sync   --pool-id us-east-1_ABC123   --emails-file cognito_sync.csv
```

Output file format:

```
username,email
alice,alice@example.com
bob,bob@example.com
carol,carol@example.com
```

This file is later used by the `add` and `del` operations.

---

## 2. Adding users to groups (add)

This operation requires two input files:

1. The sync CSV file (`username,email`)
2. A text file containing one email per line

All emails will be normalized (lowercase, trim) before lookup.

Example:

```
cogops add   --pool-id us-east-1_ABC123   --sync-file cognito_sync.csv   --emails-file to_add.txt   --group admin   --group managers   --concurrency 10
```

Where `to_add.txt` might contain:

```
alice@example.com
carol@example.com
john@example.com
```

For each email, `cogops` resolves the username from the sync map and calls the Cognito Admin API to add the user to the specified groups.

A progress bar is displayed during processing.

---

## 3. Removing users from groups (del) (WIP)

This command mirrors the `add` command but removes users instead of adding them.

Example:

```
cogops del   --pool-id us-east-1_ABC123   --sync-file cognito_sync.csv   --emails-file to_remove.txt   --group admin   --concurrency 5
```

---

## Logging and verbosity

`cogops` uses `tracing` for structured logging.

By default, logs are shown at the INFO level.\
Use `-v` to enable DEBUG logs:

```
cogops -v add ...
```

Or configure via `RUST_LOG`:

```
RUST_LOG=debug cogops add ...
```

---

## License

Licensed under ISC license ([LICENSE](LICENSE) or https://opensource.org/licenses/ISC)