diff --git a/README.md b/README.md index cd9de8e..3e2a130 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,40 @@ # SIM-CLI -[![Test and Build](https://github.com/annurdien/sim-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/annurdien/sim-cli/actions/workflows/ci.yml) -CLI tool to manage iOS simulators and Android emulators with ease. +[![Test and Build](https://github.com/annurdien/sim-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/annurdien/sim-cli/actions/workflows/ci.yml) +[![Go Version](https://img.shields.io/github/go-mod/go-version/annurdien/sim-cli)](https://golang.org) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
- SIM-CLI Terminal Icon + SIM-CLI Terminal Icon +

+ iOS Simulator & Android Emulator Manager +

+

+ A powerful, cross-platform command-line tool to streamline your mobile development workflow. +

- ## Overview -SIM-CLI is a cross-platform command-line tool that provides a unified interface for managing iOS simulators and Android emulators. It simplifies common tasks like listing devices, starting/stopping simulators, taking screenshots, and recording screen activity. +SIM-CLI provides a simple and unified interface to manage your iOS simulators and Android emulators. Say goodbye to tedious GUI interactions and manage your devices directly from the terminal. -## Features +## ✨ Features -- **Device Management**: List, start, stop, shutdown, restart, and delete simulators/emulators -- **Media Capture**: Take screenshots and record screen activity -- **Cross-Platform**: Works on macOS (with full iOS simulator support) and Linux/Windows (Android emulators only) -- **User-Friendly**: Clean, intuitive CLI interface with helpful error messages -- **Shorthand Commands**: Quick aliases for all commands (e.g., `l` for list, `s` for start) +- **📱 Device Management**: List, start, stop, shutdown, restart, and delete simulators/emulators. +- **📸 Media Capture**: Take screenshots and record screen activity with ease. +- **📋 Clipboard Integration**: Copy screenshots and recordings directly to your clipboard. +- **GIF Conversion**: Automatically convert screen recordings to GIFs. +- **🚀 Cross-Platform**: Works on macOS (with full iOS simulator support) and Linux/Windows (Android emulators only). +- **⌨️ User-Friendly**: Clean, intuitive CLI interface with helpful error messages. +- **⚡️ Shorthand Commands**: Quick aliases for all commands (e.g., `l` for list, `s` for start). +- **🧠 Smart Device Selection**: Easily start the last used device. -## Installation +## 🛠️ Installation ### Prerequisites -- **For iOS simulators**: macOS with Xcode installed -- **For Android emulators**: Android SDK with `adb` and `emulator` tools in PATH +- **For iOS simulators**: macOS with Xcode installed. +- **For Android emulators**: Android SDK with `adb` and `emulator` tools in your PATH. ### Build from Source @@ -36,171 +45,86 @@ make build ``` ### Install + ```bash make install ``` -## Usage +## 🚀 Usage ### Quick Start ```bash -# List all devices (shorthand: sim l or sim ls) +# List all available devices sim list -# Start a device (shorthand: sim s "device") +# Start a device by name sim start "iPhone 15 Pro" -# Take a screenshot (shorthand: sim ss "device") -sim screenshot "iPhone 15 Pro" - -# Stop the device (shorthand: sim st "device") -sim stop "iPhone 15 Pro" -``` - -### List Available Devices +# Take a screenshot and copy it to the clipboard +sim screenshot "iPhone 15 Pro" --copy -```bash -sim list -``` +# Record a 10-second GIF +sim record "iPhone 15 Pro" --duration 10 --gif -Example output: -``` -┌───────────────┬───────────────────────────────────────┬──────────┬──────────────────────────────────────┬──────────┐ -│ TYPE │ NAME │ STATE │ UDID │ RUNTIME │ -├───────────────┼───────────────────────────────────────┼──────────┼──────────────────────────────────────┼──────────┤ -│ iOS Simulator │ iPhone 15 Pro │ Shutdown │ AD3D3E8D-785C-4982-BADE-6D9A20D195A5 │ iOS 17.5 │ -│ iOS Simulator │ iPhone 15 Pro Max │ Shutdown │ 9A3BAC90-B6A4-43B9-A6FF-40192D23F4D1 │ iOS 17.5 │ -│ iOS Simulator │ iPhone 17.5 │ Shutdown │ 28823504-3E61-427B-BB79-C8A845A501FC │ iOS 17.5 │ -│ iOS Simulator │ iPhone 15 Plus │ Shutdown │ 323FE005-AF77-448B-AF0B-C4AC20DFBF6B │ iOS 17.5 │ -└───────────────┴───────────────────────────────────────┴──────────┴──────────────────────────────────────┴──────────┘ -``` - -### Start a Device - -```bash -# Start by name -sim start "iPhone 15 Pro" - -# Start by UDID -sim start A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6 - -# Start last started device device -sim start lts -# OR -sim s lts -``` - -### Stop a Device - -```bash +# Stop the device sim stop "iPhone 15 Pro" ``` -### Restart a Device +## 📚 Commands Reference -```bash -sim restart "Pixel_7_API_34" -``` - -### Delete a Device - -```bash -# Delete by name (⚠️ This permanently removes the device) -sim delete "iPhone 15 Pro" - -# Delete by UDID -sim delete A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6 -``` - -**Warning**: The delete command permanently removes the simulator or emulator. Use with caution! - -### Take a Screenshot - -```bash -# Auto-generated filename -sim screenshot "iPhone 15 Pro" - -# Custom filename -sim screenshot "iPhone 15 Pro" my_screenshot.png -``` - -### Record Screen - -```bash -# Record until manually stopped (Ctrl+C) -sim record "iPhone 15 Pro" - -# Record for specific duration (in seconds) -sim record "iPhone 15 Pro" --duration 30 - -# Custom filename -sim record "iPhone 15 Pro" my_recording.mp4 --duration 60 -``` - -## Commands Reference +Here is a complete list of available commands and their options. | Command | Aliases | Description | -|---------|---------|-------------| -| `list` | `l`, `ls` | List all available simulators and emulators | -| `start ` | `s` | Start a simulator or emulator | -| `stop ` | `st` | Stop a running simulator or emulator | -| `shutdown ` | `sd` | Shutdown a simulator or emulator | -| `restart ` | `r` | Restart a simulator or emulator | -| `delete ` | `d`, `del` | Delete a simulator or emulator (permanent) | -| `screenshot [file]` | `ss`, `shot` | Take a screenshot | -| `record [file]` | `rec` | Record screen activity | -| `help` | - | Show help information | -| `version` | - | Show version information | - -### Shorthand Examples +|---|---|---| +| `list` | `l`, `ls` | List all available simulators and emulators. | +| `start ` | `s` | Start a simulator or emulator. Use `lts` to start the last used device. | +| `stop ` | `st` | Stop a running simulator or emulator. | +| `shutdown ` | `sd` | Shutdown a simulator or emulator. | +| `restart ` | `r` | Restart a simulator or emulator. | +| `delete ` | `d`, `del` | **Permanently** delete a simulator or emulator. | +| `screenshot [file]` | `ss`, `shot` | Take a screenshot of a device. | +| `record [file]` | `rec` | Record screen activity of a device. | +| `last` | - | Show the last used device. | +| `lts` | - | A shorthand to start the last used device (`sim start lts`). | +| `help` | - | Show help information. | +| `version` | `-v` | Show version information. | -```bash -# These commands are equivalent: -sim list # or sim l or sim ls -sim start "device" # or sim s "device" -sim stop "device" # or sim st "device" -sim delete "device" # or sim d "device" or sim del "device" -sim screenshot "device" # or sim ss "device" or sim shot "device" -``` +### `screenshot` Options -## Device Identification +| Flag | Shorthand | Description | +|---|---|---| +| `--copy` | `-c` | Copy the screenshot to the clipboard. | -Devices can be identified by: -- **Name**: Exact device name (e.g., "iPhone 15 Pro") -- **UDID**: Unique device identifier +### `record` Options -Use `sim list` to see available devices and their identifiers. +| Flag | Shorthand | Description | +|---|---|---| +| `--duration` | `-d` | Duration of the recording in seconds (e.g., `--duration 15`). | +| `--gif` | `-g` | Convert the recording to a GIF. | +| `--copy` | `-c` | Copy the recording file path to the clipboard. | -## Safety & Best Practices -### Delete Command Safety -- The `delete` command permanently removes simulators/emulators -- Always verify the device name/UDID before deletion -- Consider using `sim list` first to confirm the exact device name -- Running devices are automatically stopped before deletion +## ⚠️ Safety & Best Practices -### iOS Simulators -- Deleted simulators can be recreated through Xcode -- Custom simulator configurations will be lost +### Delete Command -### Android Emulators -- Deleted AVDs must be manually recreated -- All data and configurations will be permanently lost +The `delete` command is destructive and **permanently removes** the simulator or emulator. -## Platform Support +- Always double-check the device name or UDID with `sim list` before deleting. +- Running devices are automatically stopped before deletion. +- Deleted devices must be recreated through Xcode (for iOS) or the AVD Manager (for Android). -- **macOS**: Full support for iOS simulators and Android emulators -- **Linux/Windows**: Android emulator support only +## 🤝 Contributing -## Contributing +Contributions are welcome! Please feel free to submit a pull request. -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Test thoroughly -5. Submit a pull request +1. Fork the repository. +2. Create your feature branch (`git checkout -b feature/AmazingFeature`). +3. Commit your changes (`git commit -m 'Add some AmazingFeature'`). +4. Push to the branch (`git push origin feature/AmazingFeature`). +5. Open a pull request. -## License +## 📄 License -MIT License - see LICENSE file for details. +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.