Help Reference
spaces --helpUsage: spaces [OPTIONS] <COMMAND>
Commands:
checkout
Executes the checkout rules in the specified scripts or workflow files.
checkout-repo
Uses git to clone a repository in a new workspace and evaluates the top level
[*]spaces.star files.
This can be used if the repository defines all of its own dependencies.
co
The shortform version of `checkout` and `checkout-repo`. The details of the command
are
loaded from `co.spaces.toml` in the current directory.
```toml
[spaces-dev.Repo]
url = "https://github.com/work-spaces/spaces"
rule-name = "spaces" # optionally checkout in a different directory - default is
from URL
rev = "main" # branch/tag/commit to checkout
new-branch = ["spaces"] # optionally create a new branch for a git repository
clone = "Default" # optionally clone type Default/Blobless
env = ["SET_VALUE=VALUE", "ANOTHER_VALUE=ANOTHER_VALUE"] # optionally add
environment variables
create-lock-file = false # optionally create a lock file
[ninja-build.Workflow]
# Loads the ninja-build-dev flow from workflows/workflows.spaces.toml
workflow = "workflows:ninja-build-dev" # Workflow to checkout or use script
script = ["workflows/preload", "workflows/ninja-build"] # Use in place of or
addition to workflow
env = ["SET_VALUE=VALUE", "ANOTHER_VALUE=ANOTHER_VALUE"] # optionally add
environment variables
new-branch = ["spaces"] # optionally create a new branch for a git repository
create-lock-file = false # optionally create a lock file
```
sync Runs checkout rules within an existing workspace
run Runs a spaces run rule.
- `spaces run`: Run all non-optional rules with dependencies
- `spaces run my-target`: Run a single target plus dependencies
- `spaces run my-target -- --some-arg --some-other-arg`: pass additional
arguments to a rule
inspect Inspect all the scripts in the workspace without running any rules.
- `spaces inspect`: show the rules that have `help` entries:
- `spaces inspect <target-name>`: show target plus dependencies
- `spaces --verbosity=message inspect`: show all rules
- `spaces --verbosity=debug inspect`: show all rules in detail
query Query workspace rules without running any of them
completions Generates shell completions for the spaces command
docs Shows the documentation for spaces starlark modules
tools Commands for managing internal spaces tools
foreach Runs a command in each repo or branch in the workspace
shell Runs an interactive shell using the workspace environment
logs Query the status of rules from the logs
store Commands for managing the spaces store (cache)
features Commands for managing feature flags
version Commands for managing the spaces version including checking for updates
run-lsp Run the Spaces language server protocol (experimental)
help Print this message or the help of the given subcommand(s)
Options:
-v, --verbosity <VERBOSITY> [default: app] [possible values: trace, debug, message, info, app,
passthrough, warning, error]
--hide-progress-bars Dont show progress bars
--show-elapsed-time Show elapsed time - use with --verbosity=debug to instrument spaces
performance
--ci If this is passed, info.is_ci() returns true in scripts
--disable-logs Disables creating log files
--rescan Rescan the workspace for *spaces.star files
-h, --help Print help
-V, --version Print versionCheckout Help
spaces checkout --helpExecutes the checkout rules in the specified scripts or workflow files.
Usage: spaces checkout [OPTIONS] --name <NAME>
Options:
--name <NAME> The name of the workspace to create
--env <ENV> Environment variables to add to the checked out workspace.
Use `--env=VAR=VALUE`. Makes workspace not reproducible.
--store <STORE> Store values in the checkout store accessible via
workspace.load_value().
Use `--store=KEY=VALUE`. Values are stored with path `//` and
url `<command line>`.
Command line store values take priority over all other path or
url values.
--new-branch <NEW_BRANCH> Use --new-branch=<rule> to have spaces create a new branch for
the rule.
Branch name will match the workspace name.
--script <SCRIPT> The path(s) to the `spaces.star` file containing checkout rules.
Paths are processed in order
--workflow <WORKFLOW> Scripts to process in the format of
`--workflow=<directory>:<script>,<script>,...`.
`--script` is processed before `--workflow`.
If <directory> has `workflows.spaces.toml`, it will be parsed
for shortcuts if only one <script> is passed.
- `spaces checkout --workflow=workflows:my-shortcut
--name=workspace-name`
- run scripts listed in `my-shortcut` in
`workflows/workflows.spaces.toml`
- `spaces checkout --workflow=workflows:preload,my-shortcut
--name=workspace-name`
- run `workflows/preload.spaces.star` then
`workflows/my-shortcut.spaces.star`
```toml
my-shortcut = ["preload", "my-shortcut"]
```
--wf <WF> Shortcut for --workflow
--create-lock-file Create a lock file for the workspace.
This file can be passed on the next checkout as a script to
re-create the exact workspace.
--force-install-tools Force install the tools spaces needs to run
--keep-workspace-on-failure Do not delete the workspace directory if checkout fails
--lock <LOCK> Override locks set in the rules.
Use `--lock=REPO=REV`. Can be used multiple times.
-h, --help Print helpRun Help
spaces run --helpRuns a spaces run rule.
- `spaces run`: Run all non-optional rules with dependencies
- `spaces run my-target`: Run a single target plus dependencies
- `spaces run my-target -- --some-arg --some-other-arg`: pass additional arguments to a rule
Usage: spaces run [OPTIONS] [TARGET] [EXTRA_RULE_ARGS]...
Arguments:
[TARGET] The name of the target to run (default is all targets)
[EXTRA_RULE_ARGS]... Extra arguments to pass to the rule (passed after `--`)
Options:
--forget-inputs Forces rules to run even if input globs are the same as last time
--skip-deps Runs only the target specified, without executing dependencies
--env <ENV> Environment variables to override during the run. Use `--env=VAR=VALUE`
-h, --help Print helpInspect Help
spaces inspect --helpInspect all the scripts in the workspace without running any rules.
- `spaces inspect`: show the rules that have `help` entries:
- `spaces inspect <target-name>`: show target plus dependencies
- `spaces --verbosity=message inspect`: show all rules
- `spaces --verbosity=debug inspect`: show all rules in detail
Usage: spaces inspect [OPTIONS] [TARGET]
Arguments:
[TARGET] The name of the target to evaluate (default is all targets)
Options:
--filter <FILTER> Filter targets with a glob (e.g. `--filter=**/my-target`)
--has-help Only show rules with the help entry populated
--checkout Inspect the command that will checkout the workspace in the current
state
--force When used with --checkout, warn if a repo is dirty but still print the
checkout command
--markdown <MARKDOWN> Write the output of the inspect command to a markdown file
--stardoc <STARDOC> Write the starlark documentation to the specified path
--fuzzy <FUZZY> Use fuzzy matching when searching for targets (e.g. `--fuzzy="my
query"`)
--details Show the rule details of the specified rule
--json Show the rule details in JSON format (works with details)
-h, --help Print help