Command line help.¶

science¶

Science helps you prepare scies for your application.

Science provides a high-level TOML manifest format for a scie application and can build scies and export scie lift JSON manifests from these configuration files.

For more information on the TOML manifest format, see: https://science.scie.app/manifest.html

science [OPTIONS] COMMAND [ARGS]...

Options

-V, --version¶: Show the version and exit.

-v, --verbose¶

Increase output verbosity.

Can be specified multiple times to further increase verbosity.

-q, --quiet¶

Decrease output verbosity.

Can be specified multiple times to further decrease verbosity.

--cache-dir <cache_dir>¶

Specify an alternate location for the science cache.

Default:: PosixPath('<USER CACHE DIR>/science')

complete¶

Generate shell completion scripts.

By default, the appropriate shell completion script for the current shell is output to stdout, but both the shell and output destination can be altered.

The use of the script depends on your shell type and preferences. To test things out you can use:

bash or zsh:
```
eval "$(science complete)"
```
fish:
```
eval (science complete)
```

To trigger option completion you must type - before tabbing.

Note

If science cannot detect your shell, or it can but is not one of the supported shells for completion, you must specify –shell.

science complete [OPTIONS]

Options

--shell <shell>¶

Specify the shell to generate a completion script for.

Default:: 'bash'
Options:: bash | fish | zsh

--output <output>¶: The file to output the shell completion script to.

doc¶

Interact with science docs.

science doc [OPTIONS] COMMAND [ARGS]...

Options

--site <site>¶

Specify an alternate URL of the doc site.

Default:: 'https://science.scie.app'

close¶

Shuts down the local documentation server.

science doc close [OPTIONS]

open¶

Opens the local documentation in a browser.

If an optional page argument is supplied, that page will be opened instead of the default doc site page.

Documentation is served by a local HTTP server which you can shut down with science doc close.

science doc open [OPTIONS] [PAGE]

Options

--remote¶

Open the official remote doc site instead.

N.B.: The official docs track the latest release of science. You’re using 0.8.1, which may not match.

Arguments

PAGE¶: Optional argument

lift¶

Perform operations against your application lift TOML manifest.

For more information on the TOML manifest format, see: https://science.scie.app/manifest.html

science lift [OPTIONS] COMMAND [ARGS]...

Options

--file <NAME=LOCATION>¶

Map paths to files defined in your manifest.

Science looks fore each non-lazy file you define at the path denoted by its name relative to the CWD you invoke science from. If any file is not at that path, you can tell science to look elsewhere with: –file <name>=<location>.

For example, for this manifest snippet:


[[lift.files]]
name = "example.txt"

If the file is located at src/examples/example.txt relative to the CWD you would specify –file example.txt=src/examples/example.txt.

--invert-lazy <FILE_ID>¶

Toggle the laziness of a file declared in the application lift manifest.

For example, for this manifest snippet:


[lift]
name = "example"

[[lift.interpreters]]
id = "cpython"
provider = "PythonBuildStandalone"
version = "3.11"

[[lift.files]]
name = "example.txt"
digest = { size = 137, fingerprint = "abcd1234" }}
source = { url = "https://example.com", lazy = false }

The default scie built will be “fat”. Both the Python Build Standalone CPython 3.11 interpreter distribution and the example.txt file will be downloaded by science and packed into the example (or example.exe on Windows) scie.

To create a “skinny” scie in addition using this same application lift manifest you can specify:


science lift --invert-lazy cpython --invert-lazy example.txt --app-name example-thin

The resulting example-thin (or example-thin.exe on Windows) scie will include the ptex binary which will be used to fetch both the Python Build Standalone CPython 3.11 interpreter distribution and the example.txt file upon first execution.

Note: only interpreter distributions and files with url sources can be toggled. Trying to toggle the laziness for other file types, like those with either no source or a binding command source, will produce an informative error.

--include-provenance¶

Include provenance information for the build in the resulting scie lift JSON manifest.

Provenance information for the science binary used to build the scie as well as provenance information for the lift manifest TOML used to create the scie will be included.

If run in a git repository, the git state will be included in git describe –always –dirty –long format.

If the application lift manifest has a [lift.app_info] table, all data in that table will be included. If any –app-info are specified, these top-level keys will also be included and over-ride any top level keys of the same name present in [lift.app_info].

For example, given the following application lift manifest snippet:


[lift.app_info]
provided_by = { sponsor = "example.org", licenses = ["Apache-2.0", "MIT"] }
edition = "free"

Running the following:


science lift \
    --include-provenance \
    --app-info edition=paid \
    --app-info releaser=$(id -un) \
    export

Would result in a scie lift JSON manifest with extra content like:


{
  "scie": {
    ...
  },
  "science": {
    "app_info": {
      "edition" = "paid"
      "provided_by": {
        "licenses": [
          "Apache-2.0",
          "MIT"
        ],
        "releaser": "jsirois",
        "sponsor": "example.org"
      }
    },
    "binary": {
      "url": "https://github.com/a-scie/lift/releases/tag/v0.1.0/science-linux-x86_64",
      "version": "0.1.0"
    },
    "git_state": "v0.1.0-0-gc423e47",
    "manifest": {
      "hash": "49dc36a6db71bccf1bff35363454f7567fd124ba80d1e488bd320668a11c70bc",
      "size": 432,
      "source": "lift.toml"
    },
    "notes": [
      "This scie lift JSON manifest was generated from lift.toml using the science binary.",
      "Find out more here: https://science.scie.app"
    ]
  }
}

--app-name <app_name>¶

Override the name of the application declared in the lift manifest.

This is particularly useful in combination with –invert-lazy to produce both “skinny” and “fat” scies from the same lift manifest. See the –invert-lazy help for an example.

--app-info <KEY=VALUE>¶

Override top-level [lift.app_info] keys or define new ones.

Implies –include-provenance whose help provides an example.

--platform <platforms>¶: Override any configured platforms and target these platforms instead.

build¶

Build scie executables from the lift TOML manifest.

If the LIFT_TOML_PATH is left unspecified, lift.toml is assumed.

science lift build [OPTIONS] LIFT_TOML_PATH

Options

--dest-dir <dest_dir>¶

The destination directory to output files to.

Default:: PosixPath('/home/runner/work/lift/lift')

--use-platform-suffix, --no-use-platform-suffix¶

Force science to use a platform suffix or omit one.

Science will automatically use a platform suffix for disambiguation. When there is no ambiguity, you can force a suffix anyway with –use-platform-suffix. Likewise, you can suppress inclusion of a platform suffix with –no-use-platform-suffix.

The current platform suffixes are:


  linux-aarch64
* linux-x86_64
  macos-aarch64
  macos-x86_64
  windows-aarch64
  windows-x86_64

Indicates the current platform.

--preserve-sandbox¶

Preserve the scie assembly sandbox and print its path to stderr.

When science builds a scie it creates a temporary sandbox to house the exported JSON lift manifest and any application files that will be included in the scie. If you preserve the sandbox, the native scie-jump binary is also included such that you can change directory to the sandbox and run scie-jump (or scie-jump.exe on Windows) to test assembling the scie “by hand”.

--use-jump <REPO_PATH>¶

The path to a clone of the scie-jump repo.

Mainly useful for testing new scie-jump fixes or integrating new scie-jump features into science. The canonical repo to clone is at https://github.com/a-scie/jump.

--hash <hash_functions>¶

Output a checksum file compatible with the shasum family of tools.

For each unique –hash specified, a sibling file to the scie executable will be generated with the same name and hash algorithm name suffix. The file will contain the hex fingerprint of the scie executable using that algorithm to hash it.

For example, for –hash sha256 against a scie named example on Windows you might get:


dist/example.exe
dist/example.exe.sha256

The contents of dist/example.exe.sha256 would look like (* means executable):


33fd890f056b0434241a357b616b4a651c82acc1ee4ce42e0b95c059d4a76f04 *example.exe

And the fingerprint of example.exe could be checked by running the following in the dist dir:


sha256sum -c example.exe.sha256
example.exe: OK

Options:: blake2b | blake2s | md5 | sha1 | sha224 | sha256 | sha384 | sha3_224 | sha3_256 | sha3_384 | sha3_512 | sha512 | shake_128 | shake_256

Arguments

LIFT_TOML_PATH¶: Optional argument

export¶

Export the lift TOML manifest as one or more scie lift JSON manifests.

science lift export [OPTIONS] LIFT_TOML_PATH

Options

--dest-dir <dest_dir>¶

The destination directory to output files to.

Default:: PosixPath('/home/runner/work/lift/lift')

--use-platform-suffix, --no-use-platform-suffix¶

Force science to use a platform suffix or omit one.

Science will automatically use a platform suffix for disambiguation. When there is no ambiguity, you can force a suffix anyway with –use-platform-suffix. Likewise, you can suppress inclusion of a platform suffix with –no-use-platform-suffix.

The current platform suffixes are:


  linux-aarch64
* linux-x86_64
  macos-aarch64
  macos-x86_64
  windows-aarch64
  windows-x86_64

Indicates the current platform.

Arguments

LIFT_TOML_PATH¶: Optional argument

provider¶

Perform operations against provider plugins.

science provider [OPTIONS] COMMAND [ARGS]...

list¶

List the installed provider plugins.

science provider list [OPTIONS]

Options

--json¶: Output the list of providers as a JSON list of objects