The metadata block of a user script must have the following format:

// ==UserScript==
// @key value_1 value_2 value_etc
// ==/UserScript==

It must use line comments // and not block comments /* */. If a key has multiple values, those values must be space-separated. The metadata block must be within the // ==UserScript== starting line and the // ==/UserScript== ending line.

Note: You can access your script's metadata at runtime with the GM_getMetadata function.

Scriptish strives to support all @keys provided by other user script engines. If there are any @keys you would like to see supported in Scriptish please create an issue (if one doesn't already exist).

Note: Unlike other user script engines, Scriptish @keys are not case sensitive.

The id, a unique identifier, for the user script. Scriptish will use the id to distinguish different user scripts, e.g. when loading script user preferences (See about:config). Also, the id might be displayed in the error/web console as a prefix to error messages generated by user scripts.

// @id [email protected]
// or
// @id plainoldtextstring

The name of a user script. This is displayed to users in the Scriptish toolbar menu and in about:addons.

// @name A Wonderful Script

This is used by other user script engines, in combination with @name, to create a unique identifier. Since Scriptish uses @id this is not currently used, but is still suggested as a possible way to group user scripts.

// @namespace http://someplace.com

This is used to grant access to GM_ functions. If you do not request access to a specific GM_ function (e.g. GM_getValue) then it will not be available to your userscript.

// @grant GM_setClipboard
// @grant GM_getValue
// @grant GM_setValue

Note: In Scriptish (currently not supported by Greasemonkey) you may specify multiple GM_ functions per @grant line. For example, you could use the following single line to replace the lines above:

// @grant GM_setClipboard GM_getValue GM_setValue

The original author of the user script, preferably with an e-mail address.

// @author Erik Vold <[email protected]> http://work.erikvold.com/

Note: We strongly recommend you use the format below, as it allows Scriptish to provide a better experience when presenting your user script in the Firefox Add-ons Manager.

// @author Fname MNames LName <[email protected]> http://website-url.com/

The names of co-developers for the user script.

// @developer Super Coder

A contributor to the user script.

// @contributor Mary Jane <[email protected]>

The user script's version. This is displayed to the user in about:addons.

Note: User scripts should specify their versions using the Toolkit version format.

// @version 2.0

A description of the user script. This is displayed to the user in about:addons.

// @description This user script kicks ass by applying boot to booty.

A homepage URL for the user script. This is displayed to the user in about:addons.

// @homepageURL http://someplace.com/userscripts/something-wonderful.html

A support URL, currently not used.

// @supportURL http://github.com/scriptish/scriptish/issues

An update URL for the user script.

The @updateURL must be secure (i.e. a https:// URL) unless the "Require user scripts to update using HTTPS" option (Scriptish Options -> Advanced -> Update Security) is set.

Note: @version is required when using @updateURL, and it must use the Toolkit version format.

Note: If the @updateURL points to a .meta.js file, Scriptish will check that for updates. If it is determined a new script version is available, Scriptish will look for a .user.js file with the same file name, domain, and path. A .meta.js is typically used instead of the .user.js file to save bandwidth and improve response time.

// @updateURL https://somedomain.com/downloads/cool-script.meta.js

An icon URL for the user script. This is displayed to the user in notifications made through GM_notification and in about:addons. The value can be a URL to an image, or a data: URL for an image.

// @icon http://someplace.com/img/kickass.png

Note: a 64px version of the icon can be provided following the icon URL, like so:

// @icon http://someplace.com/img/kickass.png http://someplace.com/img/kickass64.png

See @icon64 below for more information on the 64px version.

A 64px icon URL for the user script. This is displayed to the user in a user script's details page within about:addons. The value can be a URL to an image, or a data: URL for an image.

// @icon64 http://someplace.com/img/kickass64.png

A screenshot URL for the user script. Multiple @screenshot keys are allowed. The image may be of any type that you could use on a website. You may also, optionally, provide a thumbnail version of the image as @screenshot's second value.

// @screenshot http://something.com/some/path/img.jpg http://something.com/some/path/thumb.jpg

// @screenshot http://something.com/some/path/img.jpg

URL of a page to load if a user wishes to make a monetary contribution. This will be displayed in the user script's "More" page, accessible from the User Scripts list in the Add-ons Manager.

// @contributionURL https://m.e/donations

A suggested contribution amount. If @contributionURL is set, this will be displayed in the user script's "More" page, accessible from the User Scripts list in the Add-ons Manager.

Note: @contributionAmount is optional; only the @contributionURL is required for the contribution message to appear.

// @contributionAmount $1.00

Describes the domain name(s) a user script is allowed to run on and access through GM_xmlhttpRequest. If @domain is not defined, it is assumed the user script needs access to all domains. Multiple @domain keys are allowed.

Note: Explicitly stating the domain name(s) your user script needs to access is highly recommended, since it will provide your users with a better understanding of your script.

// @domain google.com
// @domain www.google.com

Describes the URL range on which the user script should run. Multiple @include keys are allowed.

// @include http://www.example.com/*
// @include http://*
// @include *

Note: @include may also be a regular expression literal, but only the i flag is recognized (for case-insensitivity).

// @include /^https?:\/\/(?:www\.)?google\.com\/something\//i

This comes from Google Chrome user scripts, and is a stricter version of @include. See Google Chrome's documentation on Match Patterns for further details.

// @match http://*
// @match http://*.google.com/*
// @match http://www.google.com/*

Describes the URL range to exclude (even if the page is @include'd). The value format is the same as @include.

This idea comes from the Google Chrome user script documentation (but was implemented first by Scriptish), and specifies when Scriptish will run user scripts. Scriptish (and Greasemonkey) load scripts on document-end by default, whereas Google Chrome defaults to document-idle.

The possible values for @run-at, in order of occurrence, are: document-start, document-end, document-idle and window-load.

Runs a script at the start of a page's life cycle.

// @run-at document-start

Runs a script when the DOMContentLoaded event fires.

// @run-at document-end

Runs a script some time between document-end and immediately after the window-load (i.e. window.onload()) event fires.

// @run-at document-idle

Runs a script when the window.onload() event fires.

// @run-at window-load

Specifies a script's priority level. The greater the number the greater the priority. If two or more scripts have the same @run-at value, then @priority will determine the execution order (scripts are also delayed in this order).

// @priority 1  // higher priority
// @priority -1  // lower priority
// @priority -100  // very low priority
// @priority 0 // default value

Specifies a delay, in milliseconds, before the user script is ran.

// @delay 1000

The resourceName value (see example below) must comply with JavaScript identifier restrictions. Each @resource must have a unique name.

Each @resource is downloaded during the user script installation and stored on the user's hard drive in the same folder as the script. The @resource URL may be relative to the user script's download location.

// @resource resourceName http://www.example.com/example.png
// @resource resourceName2 /example2.png
// @resource css /styles.css

GM_addStyle(GM_getResourceText('css'))

Each @css file referenced is downloaded and stored with the userscript on the hard drive, and is automatically applied to pages the userscript executes against. This makes writing CSS easier, separates CSS from JavaScript (making both easier to read), and renders GM_addStyle and use of Stylish in combination with Scriptish userscripts fairly redundant.

Each @require is downloaded during the user script installation and stored on the hard drive in the same folder as the script. The @require URL may be relative to the user script's download location.

// @require http://www.someplace.com/tools.js
// @require /tools2.js

Specifies the version of JavaScript the user script was built to work on and, if supported, will be run on. If the @jsversion provided is not acceptable the default (the highest version supported by the user's browser) will be used.

// @jsversion 1.8

If this key exists the user script will not run in iframes.

No value should be given for @noframes. If a value is provided the line will be ignored.

// @noframes