diff --git a/README.md b/README.md index 926cc3f..cac4af1 100644 --- a/README.md +++ b/README.md @@ -4,29 +4,7 @@ ![License](https://img.shields.io/badge/license-MIT-green) ![Release](https://img.shields.io/github/v/release/nylas/cli) -A unified command-line tool for Nylas API authentication, email management, calendar, contacts, webhooks, timezone utilities, and OTP extraction. - -## Features - -- **Time Zone Utilities**: ⚡ **Offline** timezone conversion, DST transitions, and meeting time finder (no API required) -- **Timezone-Aware Calendar**: View events in any timezone with `--timezone` flag, auto-detect local timezone, **DST warnings** ✅, natural language time parsing ✅ -- **Smart Meeting Finder** ✅: Multi-timezone meeting scheduling with 100-point scoring algorithm (working hours, time quality, cultural considerations) -- **AI-Powered Scheduling** (Planned): Natural language scheduling, predictive patterns, conflict resolution with privacy-first local AI (Ollama) or cloud AI (Claude, OpenAI) -- **Interactive TUI**: k9s-style terminal interface with vim-style commands, Google Calendar-style views, and email compose/reply -- **Email Management**: List, read, send, search, and organize emails with scheduled sending support -- **Calendar Management**: View calendars, list/create/delete events, check availability -- **Contacts Management**: List, view, create, and delete contacts and contact groups -- **Webhook Management**: Create, update, delete, and test webhooks for event notifications -- **Inbound Email**: Receive emails at managed addresses without OAuth (e.g., support@yourapp.nylas.email) -- **Scheduler Management**: Create and manage meeting configurations, booking pages, sessions, and bookings -- **Admin Operations**: Manage applications, connectors, credentials, and grants across your organization -- **Draft Management**: Create, edit, and send drafts -- **Folder Management**: Create, rename, and delete folders/labels -- **Thread Management**: View and manage email conversations -- **OTP Extraction**: Automatically extract one-time passwords from emails -- **Slack Integration**: List channels, read/send messages, search, and manage users -- **Multi-Account Support**: Manage multiple email accounts with grant switching -- **Secure Credential Storage**: Uses system keyring for credentials +Unified CLI for [Nylas API](https://www.nylas.com/) - manage email, calendar, and contacts across providers (Google, Microsoft, IMAP) with a single interface. ## Installation @@ -40,257 +18,74 @@ brew install nylas/nylas-cli/nylas go install github.com/nylas/cli/cmd/nylas@latest ``` -**Download Binary:** - -Download from [Releases](https://github.com/nylas/cli/releases) and add to your PATH. - -**Build from Source:** -```bash -make build -``` - -## Quick Start - -### Timezone Tools (No API Required!) +**Binary:** Download from [Releases](https://github.com/nylas/cli/releases) and add to PATH. -```bash -# Convert time between timezones -nylas timezone convert --from PST --to IST - -# Check DST transitions -nylas timezone dst --zone America/New_York --year 2026 - -# Find meeting times across multiple zones -nylas timezone find-meeting --zones "America/New_York,Europe/London,Asia/Tokyo" - -# List all timezones -nylas timezone list --filter America - -# Get timezone info -nylas timezone info UTC -``` - -### Timezone-Aware Calendar +## Getting Started +**Just want to explore?** Try the demo first - no credentials needed: ```bash -# List events in different timezone -nylas calendar events list --timezone America/Los_Angeles - -# Show timezone information for events -nylas calendar events list --show-tz - -# View specific event in multiple timezones -nylas calendar events show --timezone Europe/London -nylas calendar events show --timezone Asia/Tokyo - -# Automatic DST warnings for events near DST transitions -# ⚠️ "Daylight Saving Time begins in 2 days (clocks spring forward 1 hour)" -# ⛔ "This time will not exist due to Daylight Saving Time (clocks spring forward)" +nylas tui --demo ``` -**Features:** -- ✅ Multi-timezone event display with conversion -- ✅ Automatic DST (Daylight Saving Time) warnings -- ✅ Natural language time parsing ready for integration -- 🔄 Timezone locking (planned - Task 1.5) - -**[Full Timezone Documentation](docs/commands/timezone.md)** - -### AI-Powered Scheduling (Coming Soon) - +**Ready to connect your account?** [Get API credentials](https://dashboard.nylas.com/) (free tier available), then: ```bash -# Natural language scheduling (privacy-first with Ollama) -nylas calendar ai schedule "30-min call with john@example.com tomorrow afternoon" - -# Find optimal meeting times across timezones -nylas calendar find-time --participants alice@team.com,bob@team.com --duration 1h - -# Analyze scheduling patterns -nylas calendar ai analyze --learn-patterns - -# Auto-resolve conflicts -nylas calendar ai reschedule --reason "Urgent task" +nylas auth config # Enter your API key +nylas auth login # Connect your email provider +nylas email list # You're ready! ``` -**[Full AI Documentation](docs/commands/ai.md)** - -### Email & Calendar (Requires API) - -```bash -# Configure with your Nylas credentials -nylas auth config - -# Login with your email provider -nylas auth login - -# Launch the interactive TUI -nylas tui - -# Or use CLI commands directly -nylas email list - -# Send an email (immediately) -nylas email send --to "recipient@example.com" --subject "Hello" --body "Hi there!" - -# Send an email (scheduled for 2 hours from now) -nylas email send --to "recipient@example.com" --subject "Reminder" --schedule 2h - -# List upcoming calendar events -nylas calendar events list - -# Check calendar availability -nylas calendar availability check - -# Find optimal meeting time across timezones -nylas calendar find-time --participants alice@example.com,bob@example.com --duration 1h +## Basic Commands -# List contacts -nylas contacts list +| Command | Example | +|---------|---------| +| Email | `nylas email list`, `nylas email send --to user@example.com` | +| Calendar | `nylas calendar events list` | +| Contacts | `nylas contacts list` | +| Webhooks | `nylas webhook list` | +| TUI | `nylas tui` (interactive terminal, vim keys, [9 themes](docs/commands/tui.md)) | +| Web UI | `nylas air` (browser interface) | -# List webhooks -nylas webhook list +**[Full Command Reference →](docs/COMMANDS.md)** | **[All Documentation →](docs/INDEX.md)** -# Get the latest OTP code -nylas otp get - -# List scheduler configurations -nylas scheduler configurations list - -# List all grants (admin) -nylas admin grants list - -# List applications (admin) -nylas admin applications list -``` - ---- - -## Commands Overview - -| Command | Description | API Required | -|---------|-------------|--------------| -| `nylas timezone` | ⚡ Timezone conversion, DST, meeting finder | No | -| `nylas auth` | Authentication and account management | Yes | -| `nylas email` | Email operations (list, read, send, search) | Yes | -| `nylas calendar` | Calendar and event management | Yes | -| `nylas contacts` | Contact management | Yes | -| `nylas webhook` | Webhook configuration | Yes | -| `nylas inbound` | Inbound email inboxes (managed addresses) | Yes | -| `nylas scheduler` | Scheduler configurations, bookings, and pages | Yes | -| `nylas admin` | Administration (applications, connectors, credentials, grants) | Yes | -| `nylas otp` | OTP code extraction | Yes | -| `nylas tui` | Interactive terminal interface | Yes | -| `nylas ui` | Web-based graphical interface | Yes | -| `nylas doctor` | Diagnostic checks | No | - -**[Full Command Reference](docs/COMMANDS.md)** - ---- - -## TUI Highlights - -![TUI Demo](docs/images/tui-demo.png) - -```bash -nylas tui # Launch TUI at dashboard -nylas tui --demo # Demo mode (no credentials needed) -nylas tui --theme amber # Retro amber CRT theme -``` - -**Themes:** k9s, amber, green, apple2, vintage, ibm, futuristic, matrix, norton - -**Vim-style keys:** `j/k` navigate, `gg/G` first/last, `dd` delete, `:q` quit, `/` search - -**[Full TUI Documentation](docs/commands/tui.md)** - ---- +## Features -## Web UI +- **Email**: list, read, send, search, templates, GPG signing/encryption +- **Calendar**: events, availability, timezone conversion, AI scheduling +- **Contacts**: list, create, groups +- **Webhooks**: create, test, manage +- **Timezone**: ⚡ offline conversion, DST info, meeting finder (no API required) +- **Admin**: applications, connectors, credentials, grants +- **Integrations**: MCP (AI assistants) +- **Interfaces**: CLI, TUI (terminal), Air (web) -Launch a browser-based interface for visual CLI management: +## Timezone Tools (No API Required) ```bash -nylas ui # Start on http://localhost:7363 -nylas ui --port 8080 # Custom port -nylas ui --no-browser # Don't auto-open browser +nylas timezone convert --from PST --to IST # Convert time +nylas timezone dst --zone America/New_York # Check DST transitions +nylas timezone find-meeting --zones "NYC,LON" # Find meeting times ``` -**Features:** API configuration, account switching, email/calendar/auth commands, ID autocomplete, command history - -**Security:** Localhost only, command whitelist, shell injection protection - ---- - ## Configuration -Credentials are stored securely in your system keyring: -- **Linux**: Secret Service (GNOME Keyring, KWallet) -- **macOS**: Keychain -- **Windows**: Windows Credential Manager - -Config file location: `~/.config/nylas/config.yaml` +Credentials stored securely in system keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager). ---- - -## Documentation - -| Document | Description | -|----------|-------------| -| [Commands](docs/COMMANDS.md) | CLI command reference with examples | -| [Timezone](docs/commands/timezone.md) | Comprehensive timezone utilities guide | -| [Webhooks](docs/commands/webhooks.md) | Webhook testing and development guide | -| [TUI](docs/commands/tui.md) | Terminal UI themes, keys, customization | -| [Architecture](docs/ARCHITECTURE.md) | Hexagonal architecture overview | -| [Development](docs/DEVELOPMENT.md) | Testing, building, and contributing | -| [Security](docs/security/overview.md) | Security practices and credential handling | - ---- +Config file: `~/.config/nylas/config.yaml` ## Development -### Quick Start - ```bash -make build # Build the CLI binary -make ci # Quick quality checks (fmt, vet, lint, test-unit, test-race, security, vuln) -make ci-full # Complete CI pipeline (all checks + integration tests + cleanup) +make build # Build binary +make ci # Quality checks (fmt, vet, lint, test, security) +make ci-full # Complete CI (quality + integration tests) ``` -### Available Targets - -| Target | Description | Use When | -|--------|-------------|----------| -| `make ci-full` | **Complete validation** (quality + all tests + cleanup) | Before PRs, releases | -| `make ci` | Quality checks only (no integration tests) | Quick pre-commit check | -| `make build` | Build binary to `./bin/nylas` | Development | -| `make test-unit` | Run unit tests | Fast feedback loop | -| `make test-coverage` | Generate coverage report | Check test coverage | -| `make lint` | Run linter only | Fix linting issues | -| `make clean` | Remove build artifacts | Clean workspace | -| `make help` | Show all available targets | See all options | - -**Run `make help` for complete list of targets** - -**[Development Guide](docs/DEVELOPMENT.md)** - ---- +**[Development Guide](docs/DEVELOPMENT.md)** | **[Contributing](CONTRIBUTING.md)** ## API Reference This CLI uses the [Nylas v3 API](https://developer.nylas.com/docs/api/v3/). ---- - -## Contributing - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request - ---- - ## License MIT diff --git a/docs/INDEX.md b/docs/INDEX.md index a9747b1..86b29d3 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -63,6 +63,9 @@ Quick navigation guide to find the right documentation for your needs. ### Command Guides - **Email** → [commands/email.md](commands/email.md) +- **Email signing (GPG)** → [commands/email-signing.md](commands/email-signing.md) +- **Email encryption** → [commands/encryption.md](commands/encryption.md) +- **GPG explained** → [commands/explain-gpg.md](commands/explain-gpg.md) - **Calendar** → [commands/calendar.md](commands/calendar.md) - **Contacts** → [commands/contacts.md](commands/contacts.md) - **Webhooks** → [commands/webhooks.md](commands/webhooks.md) @@ -116,11 +119,14 @@ docs/ ├── ARCHITECTURE.md # System design ├── DEVELOPMENT.md # Development setup │ -├── commands/ # Detailed command guides (13 files) +├── commands/ # Detailed command guides (16 files) │ ├── ai.md # AI features │ ├── mcp.md # MCP integration │ ├── calendar.md # Calendar events │ ├── email.md # Email operations +│ ├── email-signing.md # GPG/PGP email signing +│ ├── encryption.md # Email encryption +│ ├── explain-gpg.md # GPG explained │ ├── contacts.md # Contact management │ ├── webhooks.md # Webhook setup │ ├── inbound.md # Inbound email @@ -200,4 +206,4 @@ docs/ --- -**Last Updated:** January 30, 2026 +**Last Updated:** February 4, 2026