commit 385db6d81b868f69681c9e6a22c1a3f26b3f613e
from: murilo ijanc <murilo@ijanc.org>
date: Tue Nov 18 19:09:53 2025 UTC

Update readme

commit - ba3f5343330cd20bb9d3b8ef372a9057d4dc50ef
commit + 385db6d81b868f69681c9e6a22c1a3f26b3f613e
blob - 8a6af3c874e44455642b422dde391a6f9b35a322
blob + 36e89dbd10f7af7c1ccbd0d99e27cc9388b6b33b
--- README.md
+++ README.md
@@ -1 +1,166 @@
-# batch-cognito
+# 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)