diff --git a/README.md b/README.md
index 51f5bea..cc78d5b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,209 @@
-# api-token-vault
+# API Token Vault
 
-A Rust CLI tool that generates, securely stores, and automatically rotates API tokens for local development
\ No newline at end of file
+[![CI](https://img.shields.io/badge/CI-Gitea%20Actions-blue)](https://7000pct.gitea.bloupla.net/7000pctAUTO/api-token-vault/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](https://opensource.org/licenses/MIT)
+[![Rust](https://img.shields.io/badge/Rust-1.70+-orange)](https://www.rust-lang.org)
+
+A Rust CLI tool that generates cryptographically secure API tokens, stores them in an encrypted local vault, rotates them on configurable schedules, and injects them into .env files. Provides multi-project isolation with separate vaults per project.
+
+## Features
+
+- **Secure Token Generation**: Generate cryptographically secure API tokens using libsodium
+- **Encrypted Vault Storage**: All tokens stored encrypted using libsodium's secretbox
+- **Auto-Rotation Schedules**: Configure automatic token rotation with configurable intervals
+- **.env File Injection**: Inject tokens directly into .env files with custom prefixes
+- **Multi-Project Isolation**: Separate vaults for different projects with independent passwords
+- **Secure Key Derivation**: Uses Argon2id for deriving encryption keys from master passwords
+
+## Installation
+
+### From Crates.io
+
+```bash
+cargo install api-token-vault
+```
+
+### From Source
+
+```bash
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-token-vault.git
+cd api-token-vault
+cargo build --release
+```
+
+The binary will be at `target/release/api-token-vault`.
+
+## Quick Start
+
+### Initialize a Vault
+
+```bash
+api-token-vault init --project my-project
+```
+
+You can also set the project via environment variable:
+
+```bash
+export API_VAULT_PROJECT=my-project
+api-token-vault init
+```
+
+### Generate a Token
+
+```bash
+api-token-vault generate --name api_key --length 32
+```
+
+### List All Tokens
+
+```bash
+api-token-vault list
+```
+
+### Get a Token Value
+
+```bash
+api-token-vault get --name api_key
+api-token-vault get --name api_key --raw  # Output only the token value
+```
+
+### Rotate a Token
+
+```bash
+api-token-vault rotate --name api_key
+api-token-vault rotate --name api_key --force  # Force rotation even if not due
+```
+
+### Set Auto-Rotation
+
+```bash
+api-token-vault set-rotation --name api_key --days 30
+```
+
+### Check Expired Tokens
+
+```bash
+api-token-vault check-expired
+```
+
+### Rotate All Expired Tokens
+
+```bash
+api-token-vault rotate-expired
+```
+
+### Inject Tokens into .env File
+
+```bash
+api-token-vault inject --env-file .env
+api-token-vault inject --env-file .env --dry-run  # Preview changes without writing
+api-token-vault inject --env-file .env --token-prefix MY_TOKEN_  # Custom prefix
+```
+
+### Delete a Token
+
+```bash
+api-token-vault delete --name api_key
+```
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize a new vault for a project |
+| `generate` | Generate a new secure API token |
+| `list` | List all tokens in the vault |
+| `get` | Get a specific token value |
+| `delete` | Delete a token from the vault |
+| `rotate` | Rotate (regenerate) a specific token |
+| `set-rotation` | Set auto-rotation schedule for a token |
+| `inject` | Inject tokens into a .env file |
+| `check-expired` | Check for expired tokens |
+| `rotate-expired` | Rotate all expired tokens |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `API_VAULT_PATH` | Custom path for vault storage directory |
+| `API_VAULT_PROJECT` | Default project name (used when not specified via CLI) |
+
+### Vault Location
+
+By default, vaults are stored in:
+- Linux/macOS: `~/.config/api-token-vault/`
+- Windows: `%APPDATA%\api-token-vault\`
+
+Each project has its own vault file: `~/.config/api-token-vault/{project_name}.json`
+
+## Security
+
+- **Encryption**: Uses libsodium's secretbox for authenticated encryption
+- **Key Derivation**: Uses Argon2id (via libsodium's pwhash) for key derivation
+- **Master Password**: Required to access each vault
+- **Salt**: Unique salt per vault for key derivation
+
+## Token Formats
+
+The tool can generate tokens in various formats:
+- **Default**: Base64-encoded secure random bytes
+- **Hex**: Hexadecimal encoded
+- **Alphanumeric**: Letters and numbers only
+- **API Key**: With custom prefix (e.g., `sk_live_xxxxx`)
+
+## Development
+
+### Build
+
+```bash
+cargo build
+cargo build --release
+```
+
+### Run Tests
+
+```bash
+cargo test
+cargo test --all
+```
+
+### Lint
+
+```bash
+cargo clippy
+```
+
+### Benchmarks
+
+```bash
+cargo bench
+```
+
+## Project Structure
+
+```
+api-token-vault/
+├── Cargo.toml
+├── Cargo.lock
+├── README.md
+├── src/
+│   ├── main.rs           # Entry point and command handling
+│   ├── cli.rs            # CLI argument parsing with clap
+│   ├── vault.rs          # Vault storage and management
+│   ├── token.rs          # Token generation and data structures
+│   ├── rotation.rs       # Token rotation scheduling
+│   ├── env_injector.rs   # .env file injection
+│   └── crypto.rs         # Cryptographic operations
+└── tests/
+    └── integration_tests.rs
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.