{"id":16228693,"url":"https://github.com/wsmd/osascript-tag","last_synced_at":"2025-07-16T11:08:05.547Z","repository":{"id":38106950,"uuid":"184192680","full_name":"wsmd/osascript-tag","owner":"wsmd","description":"📜 JavaScript template literal tag for executing OSA scripts (AppleScript, JavaScript, etc.)","archived":false,"fork":false,"pushed_at":"2023-01-03T21:01:20.000Z","size":871,"stargazers_count":10,"open_issues_count":14,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-28T19:01:21.690Z","etag":null,"topics":["apple","applescript","automation","darwin","javascript","macos","nodejs","osascript","osx"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/wsmd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-30T04:39:35.000Z","updated_at":"2023-07-23T21:58:03.000Z","dependencies_parsed_at":"2023-02-01T10:00:43.062Z","dependency_job_id":null,"html_url":"https://github.com/wsmd/osascript-tag","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/wsmd%2Fosascript-tag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmd%2Fosascript-tag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmd%2Fosascript-tag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmd%2Fosascript-tag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wsmd","download_url":"https://codeload.github.com/wsmd/osascript-tag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243995936,"owners_count":20380911,"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":["apple","applescript","automation","darwin","javascript","macos","nodejs","osascript","osx"],"created_at":"2024-10-10T12:56:10.925Z","updated_at":"2025-03-19T13:31:28.006Z","avatar_url":"https://github.com/wsmd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/2100222/57056048-ddcdd500-6c6d-11e9-8f69-e4c1d3eb4f24.png\" width=\"76\" alt=\"osascript-tag logo\" /\u003e\n  \u003cbr /\u003e\n  osascript-tag\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/osascript-tag\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/osascript-tag.svg\" alt=\"Current Release\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://travis-ci.org/wsmd/osascript-tag\"\u003e\n    \u003cimg src=\"https://travis-ci.org/wsmd/osascript-tag.svg?branch=master\" alt=\"CI Build\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/wsmd/osascript-tag?branch=master\"\u003e\n    \u003cimg src=\"https://coveralls.io/repos/github/wsmd/osascript-tag/badge.svg?branch=master\" alt=\"Coverage Status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/wsmd/osascript-tag/blob/master/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/wsmd/osascript-tag.svg\" alt=\"Licence\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nA JavaScript template literal tag that executes AppleScript and other OSA (Open Scripting Architecture) scripts.\n\nCompatible with JXA (JavaScript for Automation).\n\n## Why?\n\n\u003e Every time I get a script it's a matter of trying to know what I could do with it. I see colors, imagery. It has to have a smell. It's like falling in love. You can't give a reason why.\n\u003e\n\u003e — Paul Newman\n\n## Installation\n\nTo get started, add `osascript-tag` to your project:\n\n```\nnpm i --save osascript-tag\n```\n\n## Usage\n\n### Running AppleScript\n\nIt can be used as template literal tag to asynchronously run an AppleScript within your code. It returns a promise that resolves with the output of the script, and rejects with an error if running the script was not successful.\n\n```js\nconst osascript = require('osascript-tag');\n\nasync function main() {\n  const result = await osascript`\n    tell application \"iTunes\"\n      get { artist, name } of current track\n    end tell\n  `;\n\n  console.log(result); // \"King Gizzard \u0026 The Lizard Wizard, This Thing\"\n}\n```\n\n### Running JXA (JavaScript for Automation)\n\nTo run a JXA (JavaScript for Automation) script, use the `osascript.jxa` template tag (also available as the named export: `jxa`) . Please note that `osascript.jxa` requires macOS 10.10 or greater.\n\n```js\nconst osascript = require('osascript-tag');\n\nasync function main() {\n  await osascript.jxa`\n    const app = Application.currentApplication();\n\n    app.includeStandardAdditions = true;\n\n    app.displayNotification(\"All graphics have been converted.\", {\n      withTitle: \"My Graphic Processing Script\",\n      subtitle: \"Processing is complete.\",\n      soundName: \"Glass\",\n    });\n  `;\n}\n```\n\n### Parsing Values Returned from JXA Scripts\n\nBy default all calls to `osascript.jxa` will resolve with the stdout result as a string.\n\nIf your script, however, is expected to return parsable values, you can pass a `parse` option to `osascript.jxa` to return parsed values ready for consumption in your JavaScript code.\n\n```js\nconst osascript = require('osascript-tag');\n\nasync function main() {\n  const { artist, title } = await osascript.jxa({ parse: true })`\n    const iTunes = Application('iTunes');\n    return {\n      artist: iTunes.currentTrack.artist(),\n      title: iTunes.currentTrack.name(),\n    }\n  `;\n\n  console.log(artist); // \"King Gizzard \u0026 The Lizard Wizard\"\n  console.log(title); // \"This Thing\"\n}\n```\n\n## API\n\nThe `osascript-tag` can be used in one of the following ways:\n\n- [`osascript`](#osascript)\n- [`osascript(options: Options)`](#osascriptoptions-options)\n- [`osascript.jxa`](#osascriptjxa)\n- [`osascript.jxa(options: JXAOptions)`](#osascriptjxaoptions-jxaoptions)\n\n### `osascript`\n\nExecutes the given OSA script.\n\n##### Example\n\n```js\nconst result = await osascript`\n  tell application \"Finder\"\n    name of every file of the desktop\n  end tell\n`;\n```\n\n##### Arguments\n\n1. `script: string` - A string repressing the AppleScript code to execute\n2. `...replacements: any[]` - The replacements values\n\n##### Returns\n\nA `Promise` that resolves with the script's standard output, or rejects with an error if the scripts was not successful.\n\n### `osascript(options: Options)`\n\nExecutes the given OSA script with custom options.\n\n##### Example\n\n```js\nconst result = await osascript({ flags: 'so' })`\n  tell application \"Finder\"\n    name of every file of the desktop\n  end tell\n`;\n```\n\n##### Arguments\n\n1. `options: Options` - An object with the following keys:\n   - `flags?: string` - The flags used to modify the output of the script. It is a string consisting of any of the of the modifier characters `e`, `h`, `o`, and `s`. Defaults to `\"eh\"`. The meanings of the modifier characters are as follows:\n     - `h` Return values in human-readable form (default).\n     - `s` Return values in recompilable source form.\n     - `e` Redirect script errors to stderr (default)\n     - `o` Redirect script errors to stdout.\n   - `language?: string` - The language of the OSA script to be executed. Defaults to `\"AppleScript\"`.\n\n##### Returns\n\nAn instance of [`osascript`](#osascript) configured with the provided options.\n\n### `osascript.jxa`\n\nA convenient wrapper for `osascript` configured to run JXA.\n\n##### Example\n\n```js\nawait osascript.jxa`\n  const app = Application.currentApplication();\n  app.includeStandardAdditions = true;\n  app.displayAlert('This is a message');\n`;\n```\n\n##### Returns\n\nAn instance of [`osascript`](#osascript) configured to run JXA.\n\n### `osascript.jxa(options: JXAOptions)`\n\nExecutes a JXA script with custom options.\n\n##### Example\n\n```js\nconst result = await osascript.jxa({ parse: true })`\n  const app = Application('iTunes');\n  return {\n    artist: app.currentTrack.artist(),\n    title: app.currentTrack.name(),\n  };\n`;\n```\n\n##### Arguments\n\n1. `options: JXAOptions` - An object with the following keys:\n   - `flags?: string` - The flags used to modify the output of the script. It is a string consisting of any of the of the modifier characters `e`, `h`, `o`, and `s`. Defaults to `\"eh\"`. The meanings of the modifier characters are as follows:\n     - `h` Return values in human-readable form (default).\n     - `s` Return values in recompilable source form.\n     - `e` Redirect script errors to stderr (default)\n     - `o` Redirect script errors to stdout.\n   - `parse?: boolean` - A boolean indicating whether the standard output of the script is parsed for consumption in JavaScript. This uses `JSON.parse` under the hood. **Note that setting this option to true will automatically set the `flags` option to `\"se\"` if not set explicitly otherwise**. Defaults to `false`.\n   - `argv?: any[]` - An array of arguments to be passed to the script. This array will be available in the JXA script itself as a global variable `argv`. Please note that all values will be serialized to strings.\n\n##### Returns\n\nAn instance of [`osascript`](#osascript) configured to run JXA with custom options.\n\n## Licence\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwsmd%2Fosascript-tag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwsmd%2Fosascript-tag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwsmd%2Fosascript-tag/lists"}