Reference
API
CLI

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.

Configuration

The CLI uses an OSO_AUTH environment variable to authenticate:

export OSO_AUTH=<your_oso_api_key>

Management 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

Context facts

You may provide context facts via the -c argument to any of the Check commands. When Oso Cloud performs a check, it will consider these context facts in addition to any other facts you've previously added. Context facts are only used in the API call in which they're provided-- they do not persist across requests.

Context facts can be used to pass context from your application that you don't want to store in Oso Cloud:

  • Deep resource hierarchies: by passing has_relation(issue, "parent", issue.repository) as a context fact, you can check permissions on an issue without storing every issue -> repository relationship in Oso Cloud.
  • Claims from a user token: if users get certain roles or permissions based on their authentication token (such as a JWT), you can pass that extra information using context facts like is_admin(user).
  • Request-specific context: if you want to protect resources based on IP addresses, or time of day, or other ephemeral request properties, you can pass them as context facts with no arguments: is_weekend() or request_came_from_eu().

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

Optionally, you may provide context facts via the -c argument. Example:

oso-cloud authorize \
  -c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
  User:bob read Issue:issueOnAnvilsRepository

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

Optionally, you may provide context facts via the -c argument. Example:

oso-cloud authorize-resources \
  -c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
  -c "has_relation Issue:issueOnAcmeRepository parent Repository:acme" \
  User:bob read Issue:issueOnAnvilsRepository Issue:issueOnAcmeRepository

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

Optionally, you may provide context facts via the -c argument. Example:

oso-cloud list \
  -c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
  -c "has_relation Issue:issueOnAcmeRepository parent Repository:acme" \
  User:bob read Issue

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

Optionally, you may provide context facts via the -c argument. Example:

oso-cloud actions \
  -c "has_relation Issue:issueOnAnvilsRepository parent Repository:anvils" \
  User:bob Issue:issueOnAnvilsRepository

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

Talk to an Oso Engineer

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

Get started with Oso Cloud →