GM_* are a group of special APIs provided by Ace Script.


An object that exposes information about the current userscript. It has following properties:

  • uuid

    A unique ID of the script.

  • scriptMetaStr

    The meta block of the script.

  • scriptWillUpdate

    Whether the script will be updated automatically.

  • scriptHandler

    The name of userscript manager, which should be the string Ace Script.

  • version

    Version of Ace Script.

  • script

    An object containing structured fields from the Metadata Block:

    • description string
    • excludes array
    • includes array
    • matches array
    • name string
    • namespace string
    • resources array <string name, string url>
    • runAt string
    • version string
  • injectInto added in Ace Script v2.10.0

    The injection mode of current script. See @inject-mode for more information.


Retrieve a value for current script from storage.

GM_getValue(key, default)
  • key string

    The name for value to load.

  • default any

    The default value to return if no value exists in the storage.

Returns the retrieved value or default value.


Set a key / value pair for current script to storage.

GM_setValue(key, value)
  • key string

    The unique name for value within this script.

  • value any

    The value to be stored, which must be JSON serializable.

Returns nothing.


Delete an existing key / value pair for current script from storage.


Returns nothing.


Retrieve the list of keys of all available values within this script.


Returns an array of all available keys.


Retrieve the predefined text resource.


Returns the predefined text content.


Retrieve a BLOB URL of the predefined resource.


Returns a BLOB URL.


Creates a <style> element and injects some CSS.

.then(style => {
  console.log('This is the <style> element:', style);
  • css string

    The CSS code to inject.

Returns a Promise-like object with a .then method, which accepts a callback whose first argument is the injected <style> element.


Open URL in a new tab.

GM_openInTab(url, options)
GM_openInTab(url, openInBackground)
  • url string

    The URL to open in a new tab. URL relative to current page is also allowed.

    Note: Firefox does not support data URLs.

  • options object optional

    • boolean

      Whether the new tab should be loaded and activated.

The second usage is compatible with Greasemonkey.

  • openInBackground boolean

    openInBackground = true is the same as options = { active: false }.

Returns an object with following properties:

  • onclose

    Can be assigned to a function. If provided, it will be called when the tab opened is closed.

  • closed boolean

    Whether the tab opened is closed.

  • close function

    A function to explicitly close the tab opened.


Register a command to Ace Script popup menu.

GM_registerMenuCommand(caption, func)
  • caption string

    The name to show in the popup menu.

  • func function

    The function to execute when clicked in the menu.

If you want to add a shortcut, please see vm.shortcut.


Unregister a command which has been registered to Ace Script popup menu.

  • caption string

    The name of command to be unregistered.


Show a HTML5 desktop notification.

GM_notification(text, title, image, onclick)
  • options object

    • options.text string required

      Main text of the notification.

    • options.title string

      Title of the notification.

    • options.image string

      URL of an image to show in the notification.

    • options.onclick function

      Callback when the notification is clicked by user.

    • options.ondone function

      Callback when the notification is closed, either by user or by system.

The second usage is compatible with Greasemonkey.

  • text string required
  • title string
  • image string
  • onclick function


Set data to system clipboard.

GM_setClipboard(data, type)
  • data

    The data to be copied to system clipboard.

  • type string

    The type of data to copy. Default as text/plain.


Make a request like XMLHttpRequest, with some special capabilities.

  • details

    An object with following properties:

    • details.url string required

      URL relative to current page is also allowed.

    • details.method string

      Default as GET.

    • details.user string

      User for authentication.

    • details.password string

      Password for authentication.

    • details.overrideMimetype string

      A Mimetype to specify with the request.

    • details.headers object

      Some special headers are also allowed:

      • Cookie
      • Host
      • Origin
      • Referer
      • User-Agent
    • details.responseType string

      One of text, json, blob and arraybuffer. The default value is text.

    • details.timeout number v2.9.5+

      Time to wait for the request, none by default.

    • string | FormData | Blob

      Data to send with the request, usually for POST and PUT requests.

    • details.context any

      It can be an object and will be assigned to context of the response object.

    • details.anonymous boolean v2.10.1+

      When set to true, no cookie will be sent with the request. The default value is false.

    • Event handlers:

      • details.onabort
      • details.onerror
      • details.onload
      • details.onloadend
      • details.onprogress
      • details.onreadystatechange
      • details.ontimeout


  • details.synchronous is not supported.

Returns an object with following properties:

  • abort function

    A function to abort the request.

The response object will be passed to each event handler, with following properties:

  • status

    Same as a standard XMLHttpRequest.

  • statusText

    Same as a standard XMLHttpRequest.

  • readyState

    Same as a standard XMLHttpRequest.

  • responseHeaders

    An object of all response headers.

  • responseText

    Same as a standard XMLHttpRequest, only provided when available.

  • finalUrl

    The final URL after redirection.

  • context

    The same object passed to the original request.



Download a URL and save it as a local file.

// or
GM_download(url, name)
  • options

    An object with following properties:

    • options.url string required

      The URL to download.

    • string

      The filename to save as.

    • options.onload function

      The function to call when download started successfully.

    Properties below is the same as those for GM_xmlhttpRequest:

    • options.headers object
    • options.timeout number
    • options.onerror function
    • options.onprogress function
    • options.ontimeout function