{"id":13588371,"url":"https://github.com/socsieng/sendkeys","last_synced_at":"2025-04-05T22:07:42.093Z","repository":{"id":47421965,"uuid":"325427622","full_name":"socsieng/sendkeys","owner":"socsieng","description":"Command line tool for automating keystrokes and mouse events on macOS","archived":false,"fork":false,"pushed_at":"2024-10-24T03:37:59.000Z","size":2286,"stargazers_count":133,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-10-24T15:29:56.757Z","etag":null,"topics":["commandline","keyboard-events","keystrokes","macos","mouse-events","mousemove","sendkeys","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/socsieng.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-30T01:45:46.000Z","updated_at":"2024-10-24T03:36:37.000Z","dependencies_parsed_at":"2024-01-15T04:00:03.682Z","dependency_job_id":"7624a771-4a25-4552-9963-b342182f89ac","html_url":"https://github.com/socsieng/sendkeys","commit_stats":null,"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socsieng%2Fsendkeys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socsieng%2Fsendkeys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socsieng%2Fsendkeys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/socsieng%2Fsendkeys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/socsieng","download_url":"https://codeload.github.com/socsieng/sendkeys/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406090,"owners_count":20933803,"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":["commandline","keyboard-events","keystrokes","macos","mouse-events","mousemove","sendkeys","swift"],"created_at":"2024-08-01T15:06:40.219Z","updated_at":"2025-04-05T22:07:42.075Z","avatar_url":"https://github.com/socsieng.png","language":"Swift","readme":"# SendKeys\n\n![Build status](https://github.com/socsieng/sendkeys/workflows/build/badge.svg)\n![Homebrew installs](https://img.shields.io/github/downloads/socsieng/sendkeys/total.svg?label=%F0%9F%8D%BA+installs\u0026labelColor=32393F\u0026color=brightgreen)\n\nSendKeys is a macOS command line application used to automate the keystrokes and mouse events.\n\nIt is a great tool for automating input and mouse events for screen recordings.\n\nThis is a Swift rewrite of [`sendkeys-macos`](https://github.com/socsieng/sendkeys-macos).\n\n## Usage\n\nBasic usage:\n\n```sh\nsendkeys --application-name \"Notes\" --characters \"Hello\u003cp:1\u003e world\u003cc:left:option,shift\u003e\u003cc:i:command\u003e\"\n```\n\n![hello world example](https://github.com/socsieng/sendkeys/raw/main/docs/images/example1.gif)\n\n_Activates the Notes application (assuming Notes is already running) and types `Hello` (followed by a 1 second pause)\nand `world`, and then selects the word `world` and changes the font to italics with `command` + `i`._\n\nInput can be read from a file:\n\n```sh\nsendkeys --application-name \"Code\" --input-file example.txt\n```\n\n_Activates Visual Studio Code and sends keystrokes loaded from `example.txt`._\n\nInput can also be piped to `stdin`:\n\n```sh\ncat example.txt | sendkeys --application-name \"Notes\"\n```\n\n_Activates the Notes application and sends keystrokes piped from `stdout` of the preceding command._\n\n### Arguments\n\n- `--application-name \u003capplication-name\u003e`: The application name to activate or target when sending commands. Note that a\n  list of applications that can be used in `--application-name` can be found using the\n  [`apps` sub command](#list-of-applications-names).\n- `--pid \u003cprocess-id\u003e`: The process id of the application to target when sending commands. Note that this if this\n  argument is supplied with `--application-name`, `--pid` takes precedence.\n- `--targeted`: If supplied, the application keystrokes will only be sent to the targeted application.\n- `--no-activate`: If supplied, the specified application will not be activated before sending commands.\n- `--input-file \u003cfile-name\u003e`: The path to a file containing the commands to send to the application.\n- `--characters \u003ccharacters\u003e`: The characters to send to the application. Note that this argument is ignored if\n  `--input-file` is supplied.\n- `--delay \u003cdelay\u003e`: The delay between keystrokes and instructions. Defaults to `0.1` seconds.\n- `--initial-delay \u003cinitial-delay\u003e`: The initial delay before sending the first keystroke or instruction. Defaults to\n  `1` second.\n- `--animation-interval \u003cinterval-in-seconds\u003e`: The time between mouse movements when animating mouse commands. Lower\n  values results in smoother animations. Defaults to `0.01` seconds.\n- `--terminate-command \u003ccommand\u003e`: The command that should be used to terminate the application. Not set by default.\n  Follows a similar convention to `--characters`. (e.g. `f12:command,shift`).\n- `--keyboard-layout \u003clayout\u003e`: Use alternate keyboard layout. Defaults to `qwerty`. `colemak` and `dvorak` are also\n  supported, pull requests for other common keyboard layouts may be considered. If a specific keyboard layout is not\n  supported, a custom layout can be defined in using the `--config` option or using the\n  [`.sendkeysrc.yml`](./examples/.sendkeysrc.yml) configuration file (`send.remap`).\n- `--config \u003cyaml-file\u003e`: Configuration file to load settings from.\n\n## Installation\n\n### Homebrew (recommended)\n\nInstall using [homebrew](https://brew.sh/):\n\n```sh\nbrew install socsieng/tap/sendkeys\n```\n\n### Manual installation\n\nAlternatively, install from source:\n\n```sh\ngit clone https://github.com/socsieng/sendkeys.git\ncd sendkeys\nmake install\n```\n\n## Markup\n\nMost printable characters will be sent as keystrokes to the active application. Support for additional instructions is\nprovided by some basic markup which is unlikely to be used in other markup languages to avoid conflicts.\n\n### Key codes and modifier keys\n\nSupport for special key codes and modifier keys is provided with the following markup structure: `\u003cc:key[:modifiers]\u003e`\n\n- `key` can include any printable character or, one of the following key names: `f1`, `f2`, `f3`, `f4`, `f5`, `f6`,\n  `f7`, `f8`, `f9`, `f10`, `f11`, `f12`, `esc`, `return`, `enter`, `delete`, `space`, `tab`, `up`, `down`, `left`,\n  `right`, `home`, `end`, `pgup`, and `pgdown`. See list of\n  [mapped keys](https://github.com/socsieng/sendkeys/blob/main/Sources/SendKeysLib/KeyCodes.swift#L127) for a full list.\n- `modifiers` is an optional list of comma separated values that can include `command`, `shift`, `control`, `option`,\n  and `function`.\n\nExample key combinations:\n\n- `tab`: `\u003cc:tab\u003e`\n- `command` + `a`: `\u003cc:a:command\u003e`\n- `option` + `shift` + `left arrow`: `\u003cc:left:option,shift\u003e`\n\n#### Key down and up\n\nSome applications expect modifier keys to be pressed explicitly before invoking actions like mouse click. An example of\nthis is Pixelmator which expect the `option` key to be pressed before executing the alternate click action. This can be\nachieved with key down `\u003ckd:key[:modifiers]\u003e` and key up `\u003cku:key[:modifiers]\u003e`.\n\nNote that these command shoulds only be used in these special cases when the mouse action and modifier keys are not\nsupported natively.\n\nAn example of how to trigger alternate click behavior in Pixelmator as described above:\n`\u003ckd:option\u003e\u003cm:left:option\u003e\u003cku:option\u003e`.\n\n### Mouse commands\n\n#### Move mouse cursor\n\nThe mouse cursor can be moved using the following markup: `\u003cm:[x1,y1,]x2,y2[:duration][:modifiers]\u003e`\n\n- `x1` and `y1` are optional x and y coordinates to move the mouse from. Defaults to the current mouse position.\n- `x2` and `y2` are x and y coordinates to move the mouse to. These values are required.\n- `duration` is optional and determines the number of seconds (supports partial seconds) that should be used to move the\n  mouse cursor (larger number means slower movement). Defaults to `0`.\n- `modifiers` is an optional list of comma separated values that can include `command`, `shift`, `control`, and\n  `option`.\n\nExample usage:\n\n- `\u003cm:400,400:0.5\u003e`: Move mouse cursor from current position to 400, 400 over 0.5 seconds.\n- `\u003cm:400,400,0,0:2\u003e`: Move mouse cursor from 400, 400 position to 0, 0 over 2 seconds.\n- `\u003cm:400,400\u003e`: Move mouse cursor to 400, 400 instantly.\n\n![mouse move example](https://github.com/socsieng/sendkeys/raw/main/docs/images/mouse.gif) \u003cbr\u003e_Sample command:\n`sendkeys -c \"\u003cm:100,300,300,300:0.5\u003e\u003cp:0.5\u003e\u003cm:100,300:0.5\u003e\"`_\n\n#### Mouse click\n\nA mouse click can be activated using the following markup: `\u003cm:button[:modifiers][:clicks]\u003e`\n\n- `button` is required and refers to the mouse button to click. Supported values include `left`, `center`, and `right`.\n- `modifiers` is an optional list of comma separated values that can include `command`, `shift`, `control`, and\n  `option`.\n- `clicks` is optional and specifies the number of times the button should be clicked. Defaults to `1`.\n\nExample usage:\n\n- `\u003cm:right\u003e`: Right mouse click at the current mouse location.\n- `\u003cm:left:2\u003e`: Double click the left button at the current mouse location.\n\n#### Mouse drag\n\nA mouse drag be initiated with: `\u003cd:[x1,y1,]x2,y2[:duration][:button[:modifiers]]\u003e`\n\nThe argument structure is similar to moving the mouse cursor.\n\n- `x1` and `y1` are optional x and y coordinates to start the drage. Defaults to the current mouse position.\n- `x2` and `y2` are x and y coordinates to end the drag. These values are required.\n- `duration` is optional and determines the number of seconds (supports partial seconds) that should be used to drag the\n  mouse (larger number means slower movement). Defaults to `0`.\n- `button` is optional and refers to the mouse button to use when initiating the mouse drag. Supported values include\n  `left`, `center`, and `right`. Defaults to `left`.\n- `modifiers` is an optional list of comma separated values that can include `command`, `shift`, `control`, and\n  `option`. Note that modifiers can only be used if `button` is explicitly set.\n\nExample usage:\n\n- `\u003cd:400,400:0.5\u003e`: Drag the mouse using the left mouse button from current position to 400, 400 over 0.5 seconds.\n- `\u003cd:400,400,0,0:2:right\u003e`: Drag the mouse using the right mouse button from 400, 400 position to 0, 0 over 2 seconds.\n- `\u003cd:400,400:2:left:shift\u003e`: Drag the mouse using the left mouse button to 400, 400 over 2 seconds with the `shift` key\n  down.\n\n![mouse drag example](https://github.com/socsieng/sendkeys/raw/main/docs/images/mouse-drag.gif)\n\n#### Mouse scrolling\n\nA mouse scroll can be initiated with: `\u003cs:x,y[:duration][:modifiers]\u003e`\n\n- `x` is required and controls horizontal scrolling. Positive values scroll to the right, while negative values scroll\n  to the left.\n- `y` is required and controls vertical scrolling. Positive values scroll down, while negative values scroll up.\n- `duration` is optional and determines the number of seconds (supports partial seconds) that should be used to drag the\n  mouse (larger number means slower movement). Defaults to `0`.\n- `modifiers` is an optional list of comma separated values that can include `command`, `shift`, `control`, and\n  `option`.\n\nExample usage:\n\n- `\u003cs:0,400:0.5\u003e`: Scrolls down 400 pixels over 0.5 seconds.\n- `\u003cs:0,-100:0.2\u003e`: Scrolls up 400 pixels over 0.2 seconds.\n- `\u003cs:100,0\u003e`: Scrolls 100 pixel to the right instantly.\n\n#### Mouse focus\n\nThe mouse focus command can be used to draw attention to an area of the screen by moving the cursor in a circular\npattern. The mouse focus command uses the following markup:\n`\u003cmf:centerX,centerY:radiusX[,radiusY]:angleFrom,angleTo:duration\u003e`\n\n- `centerX` is required and represents the center x coordinate of the circular path.\n- `centerY` is required and represents the center y coordinate of the circular path.\n- `radiusX` is required and represents the size of the radius along the x axis of the circular path.\n- `radiusY` is optional and represents the size of the radius along the y axis of the circular path. If omitted,\n  `radiusX` will be used indicating that the circular path will be a regular circle. An elipse can be achieved by having\n  different values for `radiusX` and `radiusY`.\n- `angleFrom` is required and represents the start angle/position of the circular path. Angle is defined using degrees\n  where `0` represents 12 o'clock on an analog clock, and positive are applied in a clockwize direction. (e.g. 90\n  degrees is 3 o'clock).\n- `angleTo` is required and represents the end angle/position of the circular path.\n- `duration` is required and determines the number of seconds (supports partial seconds) used to complete the animation\n  between `angleFrom` to `angleTo`.\n\nExample usage:\n\n- `\u003cmf:1000,200:50,20:180,900:2\u003e`: Draws attention to position 1000, 200 by moving the mouse along an eliptical 50\n  pixels wide by 20 pixels high starting at the bottom (180 degrees) to 900 degrees (delta of 720 degrees) over a period\n  of 2 seconds.\n\n![mouse focus example](https://github.com/socsieng/sendkeys/raw/main/docs/images/mouse-focus.gif)\n\n#### Mouse path\n\nThe mouse path command can be used move the mouse cursor along a path. The mouse path command uses the following markup:\n`\u003cmpath:path[:ofssetX,offsetY[,scaleX[,scaleY]]]:duration\u003e`\n\n- `path` is required and defines path for the mouse cursor to follow. The path is described using\n  [SVG Path data](https://www.w3.org/TR/SVG/paths.html#PathData)\n- `ofssetX` and `offsetY` are optional and can be used to offset path coordinates by their respective `x` and `y`\n  values. Defaults to `0,0`.\n- `scaleX` and `scaleY` are also optional and can be used to scale path coordinates by their respective `x` and `y`\n  values. Defaults to `1,1`. If `scaleY` is omitted while `scaleX` is provided, a uniform scale will be assumed. i.e.\n  `x` = `y`.\n- `duration` is required and determines the number of seconds (supports partial seconds) used to complete the animation\n  along the `path`.\n\nExample usage:\n\n- `\u003cmpath:c0,40 200,40 200,0:2\u003e`: Moves the mouse from its current position along a cubic bezier path with control\n  points `0,40` and `200,40` to the final position of `200,1`.\n\n![mouse path example](https://github.com/socsieng/sendkeys/raw/main/docs/images/mouse-path.gif) \u003cbr\u003e_Sample command:\n`sendkeys -c \"\u003cmpath:M100,100 h 100 l5,30 10,-60 5,30 h 100:2\u003e\u003cmpath:c0,40 -220,40 -220,0:1.5\u003e\"`_\n\n#### Mouse down and up\n\nMouse down and up events can be used to manually initiate a drag event or multiple mouse move commands while the mouse\nbutton is down. This can be achieved with mouse down `\u003cmd:button[:modifiers]\u003e` and mouse up `\u003cmu:button[:modifiers]\u003e`.\n\nNote that the drag command is recommended for basic drag functionality..\n\nAn example of how include multiple mouse movements while the mouse button is down:\n`\u003cmd:left\u003e\u003cm:0,0,100,0:1\u003e\u003cm:100,100:1\u003e\u003cmu:left\u003e`.\n\n### Pauses\n\nThe default time between keystrokes and instructions is determined by the `--delay`/`-d` argument (default value is\n`0.1`). Pauses can be customized with: `\u003cp:duration\u003e`\n\n- `duration` is required and controls the amount of time to pause before the next keystroke/instruction is executed.\n\n`\u003cP:seconds\u003e` (note upper case `P`) can be used to modify the default delay between subsequent keystrokes.\n\n### Continuation\n\nA continuation can be used to ignore the next keystroke or instruction. This is useful to help with formatting a long\nsequence of character and inserting a new line for readability.\n\nInsert a continuation using the character sequence `\u003c\\\u003e`. The following instruction the sequence will be skipped over\n(including another continuation).\n\n## Transforming text for text editors\n\nSome text editors like Visual Studio Code will automatically indent or insert closing brackets which can cause\nduplication of whitespace and characters. The `transform` subcommand can help transform text files for better\ncompatibility with similar text editors.\n\nExample:\n\n```sh\nsendkeys transform --input-file examples/node.js\n```\n\nYou can also pipe the output of the `transform` command directly to your editor of choice. Example:\n\n```sh\nsendkeys transform --input-file examples/node.js | sendkeys --application-name \"Code\"\n```\n\n## Retrieving mouse position\n\nThe `mouse-position` sub command can be used to help determine which mouse coordinates to use in your scripts.\n\nFor a one off read, move your mouse to the desired position, switch to your terminal app using `command` + `tab` and\nexecute the following command:\n\n```sh\nsendkeys mouse-position\n```\n\nUse the `--watch` option to capture the location of mouse clicks, and combine it with `--output commands` to output\napproximate mouse commands that can be used to _replay_ mouse actions.\n\n```sh\n# capture mouse commands\nsendkeys mouse-position --watch --output commands \u003e mouse_commands.txt\n\n# replay mouse commands\nsendkeys --input-file mouse_commands.txt\n```\n\n## List of applications names\n\nA list of the current applications that can be activated by SendKeys (`--application-name`) can be displayed using the\n`apps` command.\n\n```sh\n# list apps that can be activated with --application-name\nsendkeys apps\n```\n\nSample output:\n\n```text\nCode             id:com.microsoft.VSCode\nFinder           id:com.apple.finder\nGoogle Chrome    id:com.google.Chrome\nSafari           id:com.apple.Safari\n```\n\nThe first column includes the application name and the second column includes the application's bundle ID.\n\nSendKeys will use `--application-name` to activate the first application instance that matches either the application\nname or bundle id (case insensitive). If there are no exact matches, it will attempt to match on whole words for the\napplication name, followed by the bundle id.\n\n## Configuration\n\nCommon arguments can be stored in a [`.sendkeysrc.yml`](./examples/.senkeysrc.yml) configuration file. Configuration\nvalues are applied and merged in the following priority order:\n\n1. Command line arguments\n2. Configuration file defined with `--config` option\n3. Configuration file defined in `~/.sendkeysrc.yml`\n4. Default values\n\n## Prerequisites\n\nThis application will only run on macOS 10.11 or later.\n\nWhen running from the terminal, ensure that the terminal has permission to use accessibility features. This can be done\nby navigating to System Preferences \u003e Security \u0026 Privacy \u003e Privacy \u003e Accessibility and adding your terminal application\nthere.\n\n![accessibility settings](https://github.com/socsieng/sendkeys/raw/main/docs/images/accessibility.gif)\n\n## Installing previous versions\n\nA specific version of the package can be installed by targeting the appropriate release artifact. Here's an example of\nthe command:\n\n```sh\nbrew install --force-bottle https://github.com/socsieng/sendkeys/releases/download/v2.3.0/sendkeys-2.3.0.catalina.bottle.tar.gz\n```\n","funding_links":[],"categories":["Swift"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocsieng%2Fsendkeys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocsieng%2Fsendkeys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocsieng%2Fsendkeys/lists"}