{"id":15669693,"url":"https://github.com/alexgustafsson/quickterm","last_synced_at":"2025-05-06T20:21:28.129Z","repository":{"id":83002417,"uuid":"319416871","full_name":"AlexGustafsson/quickterm","owner":"AlexGustafsson","description":"QuickTerm is a macOS application to allow quick interactions with a terminal, rendering its output as a sleek notification-like snackbar. Created without Xcode for macOS 11. Written in Swift 5 and SwiftUI","archived":false,"fork":false,"pushed_at":"2021-07-14T14:01:29.000Z","size":4395,"stargazers_count":7,"open_issues_count":15,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T02:34:23.633Z","etag":null,"topics":["macos","macos-application","shell","swift","swift5","swiftpm","swiftui","terminal"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexGustafsson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SupportingFiles/QuickTerm/Entitlements.plist","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-07T19:03:22.000Z","updated_at":"2025-02-13T15:33:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"a69cba36-61ca-4a70-944d-92e3e8c07dc1","html_url":"https://github.com/AlexGustafsson/quickterm","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexGustafsson%2Fquickterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexGustafsson%2Fquickterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexGustafsson%2Fquickterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexGustafsson%2Fquickterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexGustafsson","download_url":"https://codeload.github.com/AlexGustafsson/quickterm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252761759,"owners_count":21800204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["macos","macos-application","shell","swift","swift5","swiftpm","swiftui","terminal"],"created_at":"2024-10-03T14:40:46.599Z","updated_at":"2025-05-06T20:21:28.122Z","avatar_url":"https://github.com/AlexGustafsson.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/banner.png\" alt=\"Banner\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/apple/swift/releases/tag/swift-5.3.2-RELEASE\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/badge/Swift/5.3/orange\" alt=\"Swift Version 5.3\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/AlexGustafsson/quickterm/releases\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/github/release/AlexGustafsson/quickterm\" alt=\"Latest Release\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/AlexGustafsson/quickterm/blob/main/Package.swift\"\u003e\n    \u003cimg src=\"https://flat.badgen.net/badge/platform/macOS%20%2011/gray\" alt=\"Platform macOS 11\" /\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003cstrong\u003e\u003ca href=\"#quickstart\"\u003eQuick Start\u003c/a\u003e | \u003ca href=\"#contribute\"\u003eContribute\u003c/a\u003e \u003c/strong\u003e\n\u003c/p\u003e\n\n# QuickTerm\n### A macOS 11 application for quickly running shell commands\n\nNote: QuickTerm is currently being actively developed. Until it reaches v1.0.0 breaking changes may occur in minor versions.\n\n\u003ca id=\"quickstart\"\u003e\u003c/a\u003e\n## Quick Start\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/screenshots/ui.png\" alt=\"UI Screenshot\"\u003e\n\u003c/p\u003e\n\nTo install the application, download the latest release from [here](https://github.com/AlexGustafsson/quickterm/releases).\n\nOnce installed, you can start the application either via macOS's UI or the command line.\n\nTo interact with the application via the command line, it is recommended to add the following alias.\n\n```\necho 'alias quick=\"/Applications/QuickTerm.app/Contents/MacOS/QuickTerm\"' \u003e\u003e ~/.bash_profile\n```\n\nYou can now start the app like so:\n\n```\nquick\n```\n\nAnd run commands like so:\n\n```\nquick echo \"Hello, World!\"\n```\n\nA global hotkey is also available to easily run commands from anywhere. Simply press `⌥⌘T`, enter your command and press `enter`. The same UI is also available under the menu bar, `⌘ \u003e Show Command Entry`.\n\n## Table of contents\n\n[Quickstart](#quickstart)\u003cbr/\u003e\n[Features](#features)\u003cbr /\u003e\n[Installation](#installation)\u003cbr /\u003e\n[Usage](#usage)\u003cbr /\u003e\n[Screenshots](#screenshots)\u003cbr /\u003e\n[Contributing](#contributing)\n\n\u003ca id=\"features\"\u003e\u003c/a\u003e\n## Features\n\n* Familiar UI\n* Easy interaction via CLI or UI\n* Support for ANSI escape codes (upcoming)\n* Uses virtually zero resources\n* Native application written in Swift 5 and SwiftUI\n* Per-command configurations via CLI\n* Automatic dark mode\n* Spotlight-like input with command history\n* Tab-completion and auto complete (upcoming)\n* Completely configurable with automatic reload\n* Configurable, global hotkey for quick access\n\n\u003ca id=\"installation\"\u003e\u003c/a\u003e\n## Installation\n\n### Using Homebrew\n\n```sh\nbrew install --cask alexgustafsson/tap/quickterm\n```\n\n### Downloading a pre-built release\n\nDownload the latest release from [here](https://github.com/AlexGustafsson/quickterm/releases) and place `QuickTerm.app` in `/Applications`.\n\n### Build from source\n\nClone the repository.\n\n```sh\ngit clone https://github.com/AlexGustafsson/quickterm.git \u0026\u0026 cd quickterm\n```\n\nOptionally check out a specific version.\n\n```sh\ngit checkout v0.3.0\n```\n\nBuild the application.\n\n```sh\nmake build\n```\n\nOptionally sign the application.\n\n```sh\nexport CODESIGN_IDENTITY=\"Apple Development: account@example.com (ABCD123EFG)\"\nmake sign\n```\n\nCopy the built application to the applications folder.\n\n```sh\ncp -r ./build/QuickTerm.app /Applications\n```\n\n### Setup the CLI\n\nThe CLI is available in the same binary as the UI and can be run like so:\n\n```sh\n/Applications/QuickTerm.app/Contents/MacOS/QuickTerm --help\n```\n\nThough the intended usage is via an alias which you can install like so:\n\n```sh\necho 'alias quick=\"/Applications/QuickTerm.app/Contents/MacOS/QuickTerm\"' \u003e\u003e ~/.bash_profile\n```\n\n\u003ca id=\"usage\"\u003e\u003c/a\u003e\n## Usage\n\nThe application consists of three parts: the main application (UI), a communication broker (XPC service) and a CLI.\n\n### UI\n\nThe application can be started as any other. Once started, a menu bar icon (`⌘`) will appear. The menu has three available items:\n\n* About QuickTerm\n* Show Command Entry\n* Quit QuickTerm\n\nRunning a command is as simple as clicking on the Show Command Entry button and enter a command in the shown input. The same input view is also available via the global hotkey `⌥⌘T`.\n\n### CLI\n\nThe CLI enables you to easily offload commands to QuickTerm. For example, you may run `quick make` to show the build progress as you continue working on other things.\n\nTo get started with the CLI, run `quick --help` to see the available functions.\n\n```\nOVERVIEW: Run a command in a separate window\n\nUSAGE: quick [--animate] [--shell \u003cshell\u003e] [--timeout \u003ctimeout\u003e] [--keep] [--wait-for-exit] [--no-bash-profile] [--delay-after-exit \u003cdelay-after-exit\u003e] [--working-directory \u003cworking-directory\u003e] [--dump] [--print-config-path] [\u003ccommand\u003e ...]\n\nARGUMENTS:\n  \u003ccommand\u003e               Command to execute. If none is given, starts the daemon instead\n\nOPTIONS:\n  --animate               Whether or not the output should be animated as it's received. Does not work with --wait-for-exit as the output is fully available when shown\n  --shell \u003cshell\u003e         The shell to use (default: bash)\n  --timeout \u003ctimeout\u003e     The number of seconds to wait before terminating the command (default: 5.0)\n  --keep                  Whether or not the window should stay until the command finishes or is closed\n  --wait-for-exit         Whether or not to wait for the command to exit before presenting the view\n  --no-bash-profile       Don't source `~/.bash_profile` before executing the command. Applicable only when using Bash as shell\n  --delay-after-exit \u003cdelay-after-exit\u003e\n                          The number of seconds to wait after exit before closing the notification. Not used if keep is true (default: 3.0)\n  --working-directory \u003cworking-directory\u003e\n                          The working directory to run the command in. Defaults to the current working directory (default: /Users/alexgustafsson/Documents/GitHub/quickterm)\n  --dump                  Dump the command configuration as JSON. Will be used if the command is to be ran\n  --print-config-path     Print the path to the config file\n  -h, --help              Show help information.\n```\n\nThe most basic usage is to either start the UI application by simply running `quick` or to execute a command by running `quick echo \"Hello, World!\"`.\n\nAs shown in the overview above, there are also options to configure whether or not to animate the output, keep the window open even though the command has exited, when to timeout a command and so on.\n\nFor debugging purposes, one may also chose to dump the parsed command configuration by executing a command such as the following.\n\n```sh\nquick --timeout 5 --animate --shell zsh --dump echo \"Hello, World!\"\n```\n\n```json\n{\"shell\":\"zsh\",\"animate\":true,\"timeout\":5,\"keep\":false,\"workingDirectory\":\"file:\\/\\/\\/path\\/to\\/working\\/directory\\/\",\"startTime\":630156023.25511503,\"command\":\"echo Hello, World!\"}\n```\n\n### Configuration\n\nQuickTerm is fully configurable. Its config is stored in `~/.config/quickterm/config.yml`. The file is created at launch if it does not already exist. If the file cannot be parsed, the CLI will print an error, the UI will show and alert, but both will continue to work - using the default config instead.\n\nThe configuration file looks like this (without the comments):\n\n```yaml\n# Configuration for execution of commands\ncommandConfiguration:\n  # The shell to use (called like so: to /usr/bin/env \u003cshell\u003e -c \u003ccommand\u003e)\n  shell: bash\n  # The number of seconds to wait before terminating the command\n  timeout: 5e+0\n  # Whether or not the window should stay until the command finishes or is closed\n  keep: false\n  # Whether or not the output should be animated as it's received. Does not work with waitForExit as the output is fully available when shown\n  animate: false\n  # Whether or not to wait for the command to exit before presenting the view\n  waitForExit: false\n  # Source `~/.bash_profile` before executing the command. Applicable only when using Bash as shell\n  sourceBashProfile: true\n  # The number of seconds to wait after exit before closing the notification. Not used if keep is true\n  delayAfterExit: 3e+0\n  # The working directory to use for commands entered via the UI (may be disregarded, will default to CWD when started)\n  workingDirectory: /Users/alexgustafsson\nhotKeys:\n  # The global hotkey used for showing the input view (this value currently does nothing)\n  showCommandEntry: option+command+t\n```\n\nThe values should be familiar as they are the same as those configurable via the CLI on a per-command basis.\n\nThe CLI will load the config each time it's run - so the values will be updated each time. The UI / daemon watches the file for changes and will reload the config automatically.\n\nTo open the config, either use the UI via Open Configuration File, or use the CLI; `nano $(quick --print-config-path)`.\n\nTo easily show your current configuration, you can use quick:\n\n```sh\nquick 'cat $(quick --print-config-path)'\n```\n\n\u003ca id=\"screenshots\"\u003e\u003c/a\u003e\n## Screenshots\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/screenshots/cli.png\" alt=\"CLI Screenshot\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/screenshots/ui.png\" alt=\"UI Screenshot\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/screenshots/fullscreen.png\" alt=\"Fullscreen Screenshot\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/screenshots/menu.png\" alt=\"Menu Screenshot\"\u003e\n\u003c/p\u003e\n\n\u003ca id=\"contribute\"\u003e\u003c/a\u003e\n## Contribute\n\nQuickTerm is currently actively being developed and has not yet been stabilized.\n\nAny contribution is welcome. If you're not able to code it yourself, perhaps someone else is - so post an issue if there's anything on your mind.\n\nIf you're new to the open source community, Swift, GitHub or just uncertain where to begin - [issues labeled \"good first issue\"](https://github.com/AlexGustafsson/quickterm/labels/good%20first%20issue) are a great place to start. Just comment on an issue you'd like to investigate and you'll get guidance along the way.\n\n### Development\n\nAlthough you won't need to use Xcode to develop QuickTerm, it's unfortunately required as a build dependency since `xcrun` will look for `xctest` which does not exist unless you install Xcode. Although `xcrun`, `swift` and other dependencies come either pre-installed or are available via `xcode-select` or `brew`, `xctest` only comes with Xcode for now.\n\n```sh\n# Clone project\ngit clone https://github.com/AlexGustafsson/quickterm.git \u0026\u0026 cd quickterm\n\n# Show available commands\nmake\nmake help\n\n# Setup the project for development (installs git hooks)\nmake setup\n\n# Run the application (UI)\nmake run\n\n# Run the application (CLI). All arguments to the CLI must be given via the args parameter\nmake run args=\"ls\"\n\n# Tail all logs created by the application at runtime\nmake logs\n\n# Run application tests\nmake test\n\n# Lint the code\nmake lint\n\n# Format the code\nmake format\n\n# Build the application\n# Creates ./build/QuickTerm.app\nmake build\n# Build using specific flags, such as an address sanitizer\nSWIFT_FLAGS=\"--sanitize address\" make build\n\n# Sign the application\n# Use \"security find-identity -v -p codesigning\" to find available certificates.\n# Specify your identity in CODESIGN_IDENTITY\nmake sign\n\n# Package the application (does not sign the application, must be done explicitly before packaging)\n# Creates a versioned bundle zip and dmg in ./distribution\nmake package\n\n# Remove any dynamically created files\nmake clean\n```\n\n### Code layout\n\nProject-wide files such as the Makefile etc. lies at the top of the directory tree.\n\nThe `Sources` and `Tests` directory are home for source files and tests, respectively. Each project has their own directory.\n\nThe `SupportingFiles` directory contains one directory per subproject. Each project directory has files such as `Info.plist`, `Entitlements.plist` and resources (which are copied to the built app bundle).\n\nThe following directories may exist in each project's source directory:\n\n* `Components` - SwiftUI view components, such as a button etc.\n* `Controllers` - Window / view controllers\n* `Extensions` - Extensions to existing Swift classes such as `Color`\n* `Utilities` - Utilities such as algorithm implementations (`Queue` etc.)\n* `Views` - SwiftUI views\n\n### Contributors\n\nInspired by [qcmd](https://radioaktiv.zone/git/b/qcmd) by [b10rn](https://github.com/b10rn).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexgustafsson%2Fquickterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexgustafsson%2Fquickterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexgustafsson%2Fquickterm/lists"}