Skip to content

docs: streamline README for quick onboarding #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
qasim-nylas merged 1 commit into from
Feb 4, 2026
Merged

docs: streamline README for quick onboarding #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 38 additions & 243 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 <event-id> --timezone Europe/London
nylas calendar events show <event-id> --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 <event-id> --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
10 changes: 8 additions & 2 deletions docs/INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -200,4 +206,4 @@ docs/

---

**Last Updated:** January 30, 2026
**Last Updated:** February 4, 2026