Running a function

Summary#

Runs one function your app declares, with arguments, against the local platform (Running a local platform). It is the third thing you can do to an app from outside it: osy compile ships its code, osy import loads its rows, and osy run makes it do something.

The run happens as somebody. With no --as it runs anonymous — the same thing a visitor with no session gets. Name a user and it runs as that person, with their roles and row filters live.

Signature#

osy run <function> [path] [--arg NAME=VALUE] [--args-json <json>] [--as <login>] [--password <pw>] [--json]

Description#

What you can run#

Any top-level function your app declares. Methods on a class need an instance, constructors are not verbs, tests belong to osy test, and a workflow's entry points are driven by the workflow engine — each of those is refused by name, telling you which it is. Misspell a function and the answer lists the ones you can run.

osy run RecalculateTotals
osy run SendDigest --arg since=2026-08-01 --arg dryRun=true

How do I pass arguments?#

--arg NAME=VALUE binds one parameter and repeats. true, false and numbers are read as such; everything else is text, including identifiers and dates, which are converted to the parameter's declared type on arrival. Only the first = splits, so --arg filter=status=open passes status=open.

When a parameter takes an entity or a class, pass the whole argument object as JSON:

osy run PlaceOrder --args-json '{"order":{"reference":"A-1","total":42}}'

Who it runs as#

This is the part worth reading twice, because it decides what the run is allowed to do.

• No --as — the function runs anonymous. If your app denies anonymous writes, the run is refused, and that refusal is correct: it is what a stranger hitting the same code would get.
• --as <login> --password <pw> — the function runs as that user. <login> is whatever your app.Auth binds as its login field, usually an email. Their roles apply and row filters bind to them, exactly as under runas in a test. It is a real login: --as takes that user's own password, because naming a principal must never be enough to become one. Omit --password and you are prompted.

There is no switch that turns security off. A run no user could perform tells you nothing about whether your app works, and a privileged job is served by naming a user who genuinely holds that authority — add one with Adding an account, roles and all, if the app has none yet.

osy run ArchiveOldOrders --as ops@example.com --password 's3cret'

A login or password that does not check out refuses the run — as one answer, "invalid login or password", the same thing your app's own login page says. It never quietly falls back to anonymous, because a run with less authority than you asked for looks exactly like a successful one until it doesn't.

What comes back#

A function that returns a value prints it. --json gives you the whole result — whether it succeeded, what it returned, and which principal it ran as — for a script to read.

A function that refused (a validation error, a denial, a throw of your own) is reported with its own message and a non-zero exit code. That is an answer about your app, not a failure to reach it.

Against a deployed app#

osyrin app run <function> is the same command against a platform you are logged in to, with the same --as rule — which matters more there, not less.

Examples#

osy run SeedCatalogue                                  # anonymous — fine if the app allows it
osy run SeedCatalogue --as ops@example.com --password 's3cret'   # as a real user, with their rules
osy run Backfill --arg batch=500 --arg dryRun=true --json

See also#

Importing data — load the app's rows, the other half of putting it in a known state.

Compiling your app — ship the code the function comes from.

runas — the same principal idea inside a test.

The inner loop — where this sits in the build-run-look loop.