Home

stencila push

Push content to Stencila Cloud and remote services

This unified command can push sites, outputs, and remote documents. Use flags to specify what to push, or use subcommands for more control: - stencila site push for site-specific options - stencila outputs push for output-specific options

Usage

stencila push [OPTIONS] [PATH] [URL] [-- <ARGS>...]

Examples

# Push to a specific Google Doc URL
stencila push document.smd https://docs.google.com/document/d/abc123

# Push to tracked remote(s)
stencila push document.smd

# Push to Google Docs (create new or select from tracked)
stencila push document.smd --to gdoc

# Push to Microsoft 365
stencila push document.smd --to m365

# Push with execution first
stencila push report.smd -- arg1=value1

# Force create new document
stencila push document.smd --to gdoc --new

# Push everything (site, outputs, and remotes)
stencila push --all

# Push only site content
stencila push --site

# Push only outputs
stencila push --outputs

# Push only remotes (Google Docs, M365)
stencila push --remotes

# Spread push to GDocs (creates multiple docs)
stencila push report.smd --to gdoc --spread -- region=north,south

Arguments

NameDescription
[PATH]The path of the document to push (for remote push).
[URL]The URL to push to (for remote push).
[ARGS]Arguments to pass to the document for execution.

Options

NameDescription
--sitePush site content to Stencila Cloud. Possible values: true, false.
--outputsPush outputs to Stencila Cloud. Possible values: true, false.
--remotesPush to remote document services (Google Docs, Microsoft 365). Possible values: true, false.
--allPush everything (site, outputs, and remotes). Possible values: true, false.
-t, --toSelect which remote service to push to.
-n, --newCreate a new document instead of updating an existing one. Possible values: true, false.
--no-executeDo not execute the document before pushing it. Possible values: true, false.
--no-configDo not save remote to stencila.toml. Possible values: true, false.
-w, --watchEnable watch after successful push. Possible values: true, false.
-d, --directionThe sync direction (only used with --watch).
-p, --pr-modeThe GitHub PR mode (only used with --watch). Possible values: draft (Create PRs as drafts (default)), ready (Create PRs ready for review).
--debounce-secondsDebounce time in seconds (10-86400, only used with --watch).
--spreadEnable spread push mode for multi-variant execution.
--caseExplicit cases for spread=cases mode.
--titleTitle template for GDocs/M365 spread push.
--fail-fastStop on first error instead of continuing with remaining variants. Possible values: true, false.
--spread-maxMaximum number of spread runs allowed (default: 100). Default value: 100.

Possible values of --direction

ValueDescription
biBi-directional sync: changes from remote create PRs, changes to repo push to remote
from-remoteOne-way sync from remote: only remote changes create PRs
to-remoteOne-way sync to remote: only repo changes push to remote

Possible values of --spread

ValueDescription
gridCartesian product of multi-valued parameters (default)
zipPositional pairing of multi-valued parameters
casesExplicitly enumerated parameter sets via --case
© 2026 Stencila