CLI commands

Command	What it does
oren init	creates a project to use tasks
oren init worker [name]	creates a new task (--template shell|node)
oren add <source>	adds a task to the project’s local registry
oren install [pipeline]	resolves images to digests and writes oren.lock
oren validate [pipeline]	checks everything without starting a container
oren run <pipeline>	runs the pipeline
oren generate <target> <pipeline>	translates to GitLab, GitHub Actions or Cloud Build
oren authorize <pipeline>	authorises the pipeline’s accesses without running it
oren doctor	checks the prerequisites
oren cache	space used and ceiling
oren cache prune	frees the unused
oren cache limit <size>	caps the growth
oren cache clear	removes the engine and the whole cache

Account and publishing

Command	What it does
oren login	authenticates via the browser and stores a token
oren logout	forgets the local credential — does not revoke on the server
oren whoami	confirms with the server whose the stored token is
oren publish [directory]	publishes the contract and implementations of a worker
oren token list	the account’s tokens, with the last use of each
oren token revoke <id>	revokes — immediate and permanent

These need a configured registry (see Installation) and, except for login, a credential. See The portal.

logout and token revoke do different things, and the distinction matters when the reason for leaving is a suspected leak: the first forgets locally and the token stays valid on the server; the second kills it.

Common options

Option	Where	What it does
-f, --file	run, validate, install, generate	pipeline file
-r, --registry	run, validate, install, generate	local registry
-p, --properties	run, validate, authorize, generate	properties file or alias
-y, --yes	run	authorises dependencies without asking
--resume	run	reuses what the previous run produced
-v, --verbose	run	shows the engine’s progress
--frozen	install	installs what oren.lock pins, or refuses
-o, --output	generate	writes to a file instead of printing
--mode	generate	oren (one job running the CLI) or native (one job per step)
--resume	generate	the job resumes, using the platform cache
--template	init worker	shell or node
-n, --namespace	init worker	organisation that owns the task
--force	init, init worker	overwrites existing files
-i, --impl	add	which implementation to use
-p, --pipeline	add	pipeline that receives the step
--no-step	add	only registers the task; does not write to oren.yaml
-t, --token	login	pastes an existing token, instead of the browser
-n, --dry-run	publish	shows what would be published, without publishing
--private	publish	visible only to the organisation
-y, --yes	token revoke	revokes without asking

Environment variables

Variable	What it does
OREN_REGISTRY	where the published catalogue lives; beats .oren/config.json, which beats the default https://oren.sh
OREN_TOKEN	credential, for CI — makes oren login unnecessary
OREN_LANG	en or pt; without it, the system language, and English by default
OREN_SECRET_<DEP>	the content of a sensitive dependency, instead of the path
OREN_REVISION	the project’s revision, when there is no git where the pipeline runs

Only variables prefixed with OREN_ are visible to ${env.VAR} inside a pipeline. The ones in the table belong to the CLI, not to the pipeline.

OREN_SECRET_<DEP>

The name comes from the DEPENDENCY, uppercased: gcpCredential becomes OREN_SECRET_GCPCREDENTIAL. It replaces the content of what oren.yaml declares as a path — the credential file exists on your machine and not on the runner, and without this you would need a different pipeline for CI.

The value never touches the host disk: it goes in as an engine secret and is mounted straight into the container.

It only applies to a dependency declared sensitive in the type registry. Letting the environment swap a directory’s path would be a different thing, and far more dangerous: a source repointed by a variable would make the pipeline build another repository with nothing in the file changing.

A dependency written as ${env.MY_VAR} does not use this prefix — there the pipeline already said where the value comes from, and the name is the one you chose.

OREN_REVISION

Identifies the code a run built, and is recorded in its state. It is what makes --resume refuse to resume from a different commit — see Running in CI.

Without it, the CLI reads git rev-parse HEAD. Without git, the check simply does not happen: Oren does not require a repository. This variable exists for whoever runs without git and still wants the protection — every CI has that value under another name (COMMIT_SHA, CI_COMMIT_SHA, GITHUB_SHA).

Files

your-project/
├── oren.yaml              # the pipeline
├── oren.lock              # pinned images — commit it
└── .oren/
    ├── registry/          # local contracts and implementations
    ├── consent.json       # authorisations — commit it
    └── runs/<id>/         # run state — in .gitignore