Cloud

The cloud command group deploys and operates jobs on Trilogy Cloud. For a walkthrough, see Deploying Jobs and Deploy from GitHub Actions.

Usage

trilogy cloud [--api URL] [--org SLUG] [--token TOKEN] COMMAND [ARGS]...

Group options go before the subcommand: trilogy cloud --org acme sync ., not trilogy cloud sync . --org acme.

Options

Option	Description
--api URL	The Trilogy Cloud API. Defaults to production.
--org SLUG	The org to act on. Defaults to [cloud].org in trilogy.toml, or your only membership.
--token TOKEN	An API token for this invocation. Prefer TRILOGY_CLOUD_TOKEN, which keeps it out of the process arguments.
--request-timeout SECONDS	How long to wait for each API request. Defaults to 300.

Environment variables

Variable	Description
TRILOGY_CLOUD_TOKEN	The API token. Takes precedence over a stored login.
TRILOGY_CLOUD_API	The API URL, below --api and above [cloud].api_url.
TRILOGY_CLOUD_TIMEOUT	The per-request timeout in seconds.

The CLI reads [cloud].org and [cloud].api_url from the nearest trilogy.toml at or above the working directory.

Commands

Sign-in and tokens

Command	Description
login [--token TOKEN]	Sign in through the browser and store a token for this API. --token stores a pre-issued token instead.
logout	Forget the stored token.
whoami	Show the signed-in user and their orgs.
orgs	List the orgs you belong to.
tokens create NAME	Mint a personal token with your full access, in every org.
tokens create-deploy NAME	Mint an org-scoped deploy token. See below.
tokens list	List your tokens. Values are never shown.
tokens revoke TOKEN_ID	Revoke a token.

tokens create-deploy options:

Option	Description
--source [KEY]	Pin the token to a source. Bare, it pins to the current checkout; github.com/owner/repo pins to a whole repository. Put NAME before a bare --source.
--preset sync	The permissions sync needs. The default.
--prune	Also allow deleting jobs, for sync --prune.
--bind-workspace NAME	A further workspace its jobs may use. Repeatable.
--expires-in-days N	Lifetime. Defaults to 90 days.
--no-expiry	Never expire. Owner or admin only.

Deploying

Command	Description
sync [ROOT]	Deploy every project under ROOT whose trilogy.toml declares a [cloud] job.
bootstrap [ROOT]	First-time setup for a repository: sync to production, mint a pinned deploy token, and print or write the GitHub Actions workflow.

sync options:

Option	Description
--dry-run	Report what would change and write nothing.
--prune	Delete jobs whose project directory is gone. Limited to the repositories ROOT covers.
--production	Deploy to production from any branch.
--environment NAME	Deploy into the named environment, creating it if needed. An empty name means production.

Without --production or --environment, the git branch decides: main or master deploys to production, any other branch to its own environment.

bootstrap options:

Option	Description
--write-workflow [PATH]	Write the workflow file. Defaults to .github/workflows/cloud-sync.yml.
--force	Overwrite an existing workflow file.
--prune	Sync with --prune, and allow the token to delete jobs.
--no-sync	Skip the sync, for a tree that is already deployed.
--name NAME	The token's name. Defaults to ci-deploy (<repo>).
--bind-workspace NAME	As for tokens create-deploy.
--expires-in-days N, --no-expiry	As for tokens create-deploy.
--allow-local	Allow a directory with no git remote. The token then covers only the project at ROOT.
--dry-run	Sync dry and mint nothing.

Jobs and workspaces

Command	Description
jobs list	List the org's jobs.
jobs run JOB [--wait] [--logs]	Trigger a run by name or id. Without --wait it returns once the run is queued. With --wait it blocks until the run finishes, and exits non-zero unless the run completed.
jobs versions JOB	A job's version history, newest first.
jobs fetch JOB	Write a job's files to a local directory. --resolved includes the files it inherits from its workspace.
jobs push --name NAME	Push a local directory as a job, by name. For one-off jobs; prefer sync.
jobs delete JOB...	Delete jobs and their run history.
workspaces list	List the org's workspaces.
workspaces jobs WORKSPACE	List the jobs that run from a workspace, with each one's entrypoint.
workspaces fetch WORKSPACE	Write a workspace's files to a local directory.
workspaces push --name NAME	Push a local directory as a workspace.

Runs and schedules

Command	Description
runs list [--limit N] [--status S] [--source manual|scheduled]	Recent runs across the org.
runs show RUN_ID	A run's timeline and per-file results.
runs wait RUN_ID	Block until a run finishes; exit non-zero unless it completed.
runs logs RUN_ID [--stream stderr|stdout|exec_log] [-o FILE]	A run's complete log. runs show prints only an excerpt.
schedules list	List the org's schedules.
schedules create JOB... --name NAME --cron EXPR	Schedule one or more jobs. Jobs on one schedule run in dependency order.
schedules delete SCHEDULE_ID	Delete a schedule.

A sync manages the schedules declared in [cloud] blocks. Use schedules for jobs deployed another way.

Environments and secrets

Command	Description
env label [BRANCH]	Print the environment a branch maps to; prints nothing for main. Needs no login.
env list	List environments and their job counts.
env create NAME	Create an environment. Returns the existing one if the name is taken.
env fork SOURCE NAME	Copy an environment's jobs, or production's (default), into a new one.
env delete NAME --with-jobs	Delete an environment and its jobs. --keep-jobs moves the jobs into production instead.
secrets set NAME [--value V]	Create or update an org secret. Prompts for the value when omitted.
secrets list	List secret names. Values are never returned.
secrets delete NAME	Delete a secret.

Machine-readable output

The global --format json flag makes every cloud command emit newline-delimited JSON events:

trilogy --format json cloud --org acme runs list --status failed