Help Reference
$ spaces --help
Usage: 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
# Repo entries can derive from another checkout entry and override selected fields
[spaces-dev-base.Repo]
url = "https://github.com/work-spaces/spaces"
rule-name = "spaces"
rev = "main"
[spaces-dev-fork.RepoDerived]
derive-from = "spaces-dev-base"
url = "https://github.com/my-org/spaces"
rev = "feature-branch"
[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
query-co Query checkout entries from co.spaces.toml
completions Generates shell completions for the spaces command
docs Shows the documentation for spaces starlark modules
about Shows the spaces logo and version
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
--create-digest-reports Create per-rule digest reports under `.spaces/digests` when running
rules
-h, --help Print help
-V, --version Print versionCheckout Help
$ spaces checkout --help
Executes 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 --help
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
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 helpQuery Help
$ spaces query --help
Query workspace rules without running any of them
Usage: spaces query <COMMAND>
Commands:
rules List rules in the workspace.
- `spaces query rules`: show run rules
- `spaces query rules --filter='**/my-pkg:*'`: filter by glob pattern
- `spaces query rules --filter='//my-pkg/**'`: filter by label-style glob prefix
- `spaces query rules --has-help`: show only rules with help populated
- `spaces query rules --checkout`: include checkout-phase rules
- `spaces query rules --deps`: include expanded deps and targets in output
- `spaces query rules --raw`: emit full task YAML per rule
rule Show details for a specific rule.
- `spaces query rule //my-pkg:build`: show rule details in YAML
- `spaces query rule //my-pkg:build --format=json`: show rule details in JSON
- `spaces query rule //my-pkg:build --deps`: include expanded deps in output
- `spaces query rule //my-pkg:checkout --checkout`: search checkout-phase rules
search Search for rules using fuzzy matching and filters.
- `spaces query search build`: return top 10 matches for 'build'
- `spaces query search build test`: return top 10 matches across all terms
- `spaces query search //my-pkg`: filter rules starting with //my-pkg
- `spaces query search some/path`: filter rules that contain some/path
- `spaces query search :build`: filter rules containing :build
- `spaces query search //pkg build`: filter by //pkg prefix, then fuzzy search 'build'
- `spaces query search build --deps`: include expanded deps and targets in results
- `spaces query search build --limit=20`: return top 20 matches
- `spaces query search build --checkout`: include checkout-phase rules in search
checkout Print the command to reproduce the current workspace checkout.
- `spaces query checkout`: print the checkout command
- `spaces query checkout --force`: print even if a repo is dirty
export Export workspace documentation.
- `spaces query export ./docs/rules.md`: export rules as a markdown file
- `spaces query export ./docs/rules.md --checkout`: include checkout-phase rules in
markdown
- `spaces query export ./docs/api --format=stardoc`: export starlark module docs to a
directory
- For stardoc, PATH is a base directory; one .md file is written per .star module
(mirrors `spaces inspect --stardoc`)
- Stardoc always requires --format=stardoc; omitting --format defaults to markdown
graph Show dependency graph for a specific rule.
- `spaces query graph //my-pkg:build`: show dependency tree for the rule
- `spaces query graph //my-pkg:build --format=json`: output as JSON
- `spaces query graph //my-pkg:build --format=yaml`: output as YAML
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print helpSync Help
$ spaces sync --help
Runs checkout rules within an existing workspace
Usage: spaces sync [OPTIONS]
Options:
--env <ENV>
Environment variables to add to the workspace.
Use `--env=VAR=VALUE`. Makes workspace not reproducible.
--store <STORE>
Store values 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.
--no-store <NO_STORE>
Remove a store value previously set via --store=KEY=VALUE.
Use `--no-store=KEY`. Removes the named key from the command-line store entry.
--dev-branch <DEV_BRANCH>
Use --dev-branch=<repo-path> to add a repo to the dev-branch list.
Unlike --new-branch, this does not create a new git branch.
--new-branch <NEW_BRANCH>
Use --new-branch=<repo-path> to create a new branch from the repo's configured workspace
rev.
The new branch name matches the workspace name and the repo is marked as a dev-branch.
This flag can be used multiple times.
--no-dev-branch <NO_DEV_BRANCH>
Use --no-dev-branch=<repo-path> to remove a repo from the dev-branch list.
This has the opposite effect of --dev-branch.
--stash
Stash uncommitted changes before sync and pop the stash after sync.
This allows syncing dirty repositories without manually stashing.
--allow-dirty
Same as --skip-pre-evaluation. This option will be removed in a future version.
--skip-pre-evaluation
Skip repository status checks and rebase operations.
Use with caution: this bypasses safety checks for dirty repos and rebase conflicts.
--merge <MERGE>
For matching dev-branch repos, merge instead of rebase.
Use `--merge=<repo-path>`. This flag can be used multiple times.
--no-rebase-repo <NO_REBASE_REPO>
For matching dev-branch repos, skip both rebase and merge.
Use `--no-rebase-repo=<repo-path>`. This flag can be used multiple times.
--no-rebase
Skip rebase for all dev-branch repos unless explicitly listed in `--merge`.
--dev-branch-base <DEV_BRANCH_BASE>
Override sync base ref for a repo.
Use `--dev-branch-base=<repo-path>=<ref>`. This flag can be used multiple times.
Useful for dev-branch rebases/merges and for non-branch rev repos checked out on a local
branch.
--no-dev-branch-base <NO_DEV_BRANCH_BASE>
Remove a stored sync base override for a repo.
Use `--no-dev-branch-base=<repo-path>`. This has the opposite effect of
--dev-branch-base.
--dry-run
Run sync pre-evaluation planning only and print what would happen.
Does not modify repositories and does not execute evaluation tasks.
--skip-evaluation
Skip Starlark evaluation and task execution.
Still runs sync pre-evaluation and sync post-evaluation actions, including branch
updates and stash pop.
--locked
The workspace lock rev's will override the rule rev for repos during sync
-h, --help
Print help