-
Notifications
You must be signed in to change notification settings - Fork 0
docs: update README to enhance clarity and add feature descriptions #12
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.
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
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,31 +1,40 @@ | ||
| # SIM-CLI | ||
| [](https://github.com/annurdien/sim-cli/actions/workflows/ci.yml) | ||
|
|
||
| CLI tool to manage iOS simulators and Android emulators with ease. | ||
| [](https://github.com/annurdien/sim-cli/actions/workflows/ci.yml) | ||
| [](https://golang.org) | ||
| [](https://opensource.org/licenses/MIT) | ||
|
|
||
| <div align="center"> | ||
| <img src="./assets/cli.png" alt="SIM-CLI Terminal Icon"> | ||
| <img src="./assets/cli.png" alt="SIM-CLI Terminal Icon" width="600"> | ||
| <p> | ||
| <strong>iOS Simulator & Android Emulator Manager</strong> | ||
| </p> | ||
| <p> | ||
| A powerful, cross-platform command-line tool to streamline your mobile development workflow. | ||
| </p> | ||
| </div> | ||
|
|
||
|
|
||
| ## 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 <device>` | `s` | Start a simulator or emulator | | ||
| | `stop <device>` | `st` | Stop a running simulator or emulator | | ||
| | `shutdown <device>` | `sd` | Shutdown a simulator or emulator | | ||
| | `restart <device>` | `r` | Restart a simulator or emulator | | ||
| | `delete <device>` | `d`, `del` | Delete a simulator or emulator (permanent) | | ||
| | `screenshot <device> [file]` | `ss`, `shot` | Take a screenshot | | ||
| | `record <device> [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 <device>` | `s` | Start a simulator or emulator. Use `lts` to start the last used device. | | ||
| | `stop <device>` | `st` | Stop a running simulator or emulator. | | ||
| | `shutdown <device>` | `sd` | Shutdown a simulator or emulator. | | ||
| | `restart <device>` | `r` | Restart a simulator or emulator. | | ||
| | `delete <device>` | `d`, `del` | **Permanently** delete a simulator or emulator. | | ||
| | `screenshot <device> [file]` | `ss`, `shot` | Take a screenshot of a device. | | ||
| | `record <device> [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. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[nitpick] Missing 'Auto' prefix for consistency. Should be 'Auto GIF Conversion:' to match the pattern of other feature descriptions that use descriptive prefixes.