Client APIs
Command-Line Interface

Command-Line Interface (CLI)


Before going through this guide, make sure you follow the Oso Cloud Quickstart to get your Oso API Key properly set in your environment.


The CLI uses an OSO_AUTH environment variable to authenticate:

export OSO_AUTH=<your_oso_api_key>

Write API

Add fact: oso-cloud tell <predicate> ([<type>:]<id> )*

Writes a fact named <predicate> with the specified arguments. Arguments for which <type> is omitted are given type String. Example:

oso-cloud tell has_role User:bob "owner" Organization:acme

Delete fact: oso-cloud delete <predicate> ([<type>:]<id> )*

Deletes a written fact. Does not throw an error if the fact is not found. Example:

oso-cloud delete has_role User:bob "maintainer" Repository:anvil

Get fact: oso-cloud get {_, <predicate>} ({_, <type>}:{_, <id>} )*

Gets all written facts matching the specified predicate and arguments. Use _ in place of a predicate, type, or id to match anything. You can also _ use as shorthand for _:_ to match arguments with any type and id. Example:

oso-cloud get has_role _ "maintainer" Repository:_

Inspect object: oso-cloud inspect {_, <type>}:{_, <id>}

Gets all written facts for which <type>:<id> is an argument. As with oso-cloud get, you can use _ in place of <type> or <id> to match anything. Example:

oso-cloud inspect User:bob

Check API

Check a permission: oso-cloud authorize <actor> <action> <resource>

Determines whether or not an action is allowed, based on a combination of authorization data and policy logic. Example:

oso-cloud authorize User:bob read Repository:anvils

Check authorized resources: oso-cloud authorize-resources <actor> <action> (<resource>)*

Returns a subset of resources on which an actor can perform a particular action. Ordering and duplicates, if any exist, may not be preserved.

oso-cloud authorize-resources User:bob read Repository:anvils Repository:acme

List authorized resources: oso-cloud list <actor> <action> <resource-type>

Fetches a list of resources on which an actor can perform a particular action. Example:

oso-cloud list User:bob read Repository

List authorized actions: oso-cloud actions <actor> <resource>

Fetches a list of actions which an actor can perform on a particular resource. Example:

oso-cloud actions User:bob Repository:anvils

Policy API

Update the active policy: oso-cloud policy <policy-file>

Updates the policy in Oso Cloud. The file passed into this method should be written in Polar. CLI usage:

oso-cloud policy main.polar

Monitoring API

View logs for recent requests: oso-cloud monitor

View JSON-formatted logs for recent requests to Oso Cloud. CLI usage:

oso-cloud monitor

Backup API

Create a backup

Create a backup based on a current snapshot of the Oso service:

oso-cloud backups add <NAME>

Restore a backup

Restore from an existing backup:

oso-cloud backups restore <BACKUP_KEY>

A list of backups and their <BACKUP_KEY>s can be obtained using the list command.

List available backups

List available backups:

oso-cloud backups list

Delete a backup

Delete an existing backup:

oso-cloud backups delete <BACKUP_KEY>

A list of backups and their <BACKUP_KEY>s can be obtained using the list command.

Talk to an Oso Engineer

Our team is happy to help you get started with Oso. If you'd like to learn more about using Oso in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer.

Get started with Oso Cloud →

Last updated on May 26, 2022