Scoop Application Manifest Guide

To begin, I’ll explain the quickest way to add an application to a Scoop bucket, using the portable SwiftSearch application as an example.

JSON Manifest File

It’s a simple JSON file that can be formatted as such. Scoop must be able to independently detect a new version of the application when it becomes available on the website and automatically download the installation file and run it. The JSON manifest has a multitude of options that I won’t explain here, but they are well-explained on App Manifests. As usual, reviewing examples of JSON manifests for other applications is an excellent source of information.

Creating a Manifest

There are nearly unlimited ways to create a proper JSON manifest, but I’ll give you two easy examples.

One way to create an empty skeleton JSON manifest for your application is by knowing the exact download URL for it. In this case, I am using a Gist URL for a simple Hello.ps1 app created by the Scoop author specifically as sample material for working with JSON manifests:

scoop create https://gist.github.com/lukesampson/6446238/raw/hello.ps1

As the JSON manifest file is being created, the computer will prompt you for the name of the JSON file and the starting version of your app. Essentially, it doesn’t matter what you input as we still have a lot of work to do for this manifest to be useful. So, it’s perfectly okay to automate these answers and create the file with just one command:

1
2

# create minimal example manifest without answering to questions
'example', '0.0' | powershell -c "scoop create https://gist.github.com/lukesampson/6446238/raw/hello.ps1"

And now, let’s create a completely valid JSON in one go, for demonstration purposes.

1
2

# this manifest is valid from the start
'{ "version": "1.0", "url": "https://gist.github.com/lukesampson/6446238/raw/hello.ps1#/example.ps1", "hash": "0", "bin": "example.ps1" }' > example.json

Don’t forget to confirm that the JSON file was successfully generated with cat example.json. Otherwise, at any time you can view the content of any application’s manifest with scoop cat AnyApp.

It’s recommended to format your Scoop manifest using the formatjson script. This, along with many other useful tools, can be found in the Scoop bin path which is located, by default, within your user’s home folder. To access your home folder in PowerShell, you can either use the tilde (~) or the $env:userprofile variable. It doesn’t matter which one you use, you can type either ~/scoop/... or $env:userprofile/scoop/....

Let’s finally take the time to format our JSON file:

~/scoop/apps/scoop/current/bin/formatjson example .

Note that it’s important to include the ./ dot in front of the JSON filename if your manifest file is located in the current directory.

Validate JSON Syntax

Basic Syntax Check

To start with, if you have scoop install jq installed, just do this:

cat .\example.json | jq

Also you can directly run a JSON syntax check without having jq installed.

npx jsonlint example.json

Only after done this, can you move on to checking the JSON format according to the JSON schema.

Compliance with JSON Schema

The scoop install scoop-validator tool is crucial for me in development, as it verifies my JSON file against a JSON Schema:

validator $env:userprofile\scoop\apps\scoop\current\schema.json ./example.json

Bear in mind that the file will often work correctly even if it doesn’t pass this check entirely.

Verifying URLs and Hashes

First and foremost, double-check that every URL listed in your Scoop manifest is accessible:

~/scoop/apps/scoop/current/bin/checkurls example .

While all the URLs may be reachable, it’s still possible for the files to not be downloading properly because the URL must point to a direct-download file. Once you’ve confirmed the proper download URL, input the hash field for that download. Make sure the hash in the manifest is accurate:

~/scoop/apps/scoop/current/bin/checkhashes example .

If it isn’t, and if the hash differs, simply add the -Update flag to have the updated, correct hash automatically written to the manifest:

~/scoop/apps/scoop/current/bin/checkhashes example . -Update 

Now that the hash of the download file is correct, you can verify if a new version check is working.

Validate Version Checks

Before moving forward, let’s make sure your manifest file has the necessary checkver and autoupdate properties. You can validate this by running the following command:

~/scoop/apps/scoop/current/bin/missing-checkver example .

If the checkver field is missing, you can easily add it with the following format:

"checkver": {
    "url": "",
    "regex": ""
}

Note that there are various variations available, and there are also special cases in the form of shorthand values for well-known websites like "checkver": "swiftsearch" or "checkver": "github".

It’s time to finally check if the version-check system is working by using the checkver script.

~/scoop/apps/scoop/current/bin/checkver swiftsearch .

If the system isn’t active, nothing will be displayed as a result of this command. If it is active but there are no new versions, the previous version will still be displayed.

Simulating Auto-Update

Now that we’ve confirmed that the version check system is definitely working (using the checkver script), we need to specify the format of the URL in the autoupdate field of the manifest, using the $version variable:

"autoupdate": {
  "url": "https://down... ... /$version/example.exe"
}

Then, we’ll use the -Update option to automatically update the manifest, populating both the Version and Url fields, using the template within the autoupdate/url field.

~/scoop/apps/scoop/current/bin/checkver swiftsearch . -Update

You may need to use the -ForceUpdate (shortcut -f) parameter, which will download the latest version and update the hash field, even if there are no new versions.

You can force a specific version by adding the -Version "some.another" option to simulate the situation as if it were the current o aktuelna verzija.

~/scoop/apps/scoop/current/bin/checkver swiftsearch . -Version "7.5" -Update

With this command, I can modify it as if it was created for a previous version, which then allows me to fully simulate the auto-update mechanism, as the next launch of the “Update” command without parameters will conduct a proper real-world testing.

End-to-End Final Testing

Before a proper trial installation, we can verify that the download is correct by downloading the application to the cache folder and verifying hashes:

scoop download swiftsearch

However, the ultimate testing is only when we attempt to install and then remove the application, which in our example is fast and simple, but with large packages, it may not be so.

Using our small example.json manifest, it would look like this:

1
2
3
4
5
6
7
8

# install example app
scoop install example

# test new app; should output Hello
example

# remove
scoop uninstall --purge example

Or in the case of a more complicated application:

scoop install ./swiftsearch.json
scoop uninstall --purge ./swiftsearch.json

Tidbits on Manifesting

Most operations from the scoop/bin folder can be run on the entire folder and all manifests within it.

You can try having scoop automatically extract the app description from its homepage, with:

~/scoop/apps/scoop/current/bin/describe swiftsearch .

The scoop config command allows you to tweak and inspect your configuration, with a particularly interesting option for debugging:

scoop config debug $true

As a reminder, here are some noteworthy tidbits regarding the values of JSON Manifest properties:

• The checkver property uses a regular expression to identify the current stable version.
• By default, hash uses SHA256, but you can specify others with prefixes like sha512:, sha1:, or md5:.
• To rename the downloaded filename, append an URL fragment that starts with #/, as explained