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 all facts matching the specific arguments. Does not throw an error if the fact is not found. Example:


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


# delete all user roles from the repository
oso-cloud delete has_role User:_ _ Repository:anvil

ℹ️

For Oso Cloud developer accounts, Get and Inspect calls are limited to 1000 results. If you have more than 1000 facts, the CLI will return an error.

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

ℹ️

For Oso Cloud developer accounts, * the number of context facts per request is limited to 20; and * the number of records returned is limited to 1000.

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.

ℹ️

For Oso Cloud developer accounts, the number of input resources is limited to 1000.


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

Query for anything: oso-cloud query <predicate> (<actor|resource>)*

Query Oso Cloud for any predicate and any combination of concrete and wildcard arguments. Unlike oso-cloud get, which only lists facts you've added, you can use oso-cloud query to list derived information about any rule in your policy. Examples:


# Query for all the repos `User:bob` can `read`
oso-cloud query allow User:bob read Repository:_
# Query for all the objects `User:admin` can `read`
oso-cloud query allow User:admin read _

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


# Query for all the repos `User:bob` can `write` derived from context facts
oso-cloud query \
-c "has_permission User:bob write Repository:anvils"
User:bob write Repository:_

Note that _ behaves like a wildcard. Passing allow _ _ Repository:anvils means "find anyone who can do anything to Repository:anvils". _ also behaves like a wildcard in return values from query. Additionally, if you want to query over all instances of a particular type, pass in a resource type with a wildcard id. For example, allow User:bob read Repository:_ will query for all the objects of type "Repository" that User:bob can read.

Learn more about how to query Oso Cloud.

Policy API

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

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


oso-cloud policy main.polar

By default, this command will run any tests defined in your policy. If one or more of these tests fail, your policy will not be updated.

You can override this behavior by passing the --force flag:


oso-cloud policy main.polar --force

This will allow you to update a policy with failing test assertions.

Multiple policies

The oso-cloud policy command can also take in multiple policy files. This command concatenates together the policies, and then uploads them. Ordering of policies does not matter.

Test your policy: oso-cloud test <policy-file> <policy-file2> ...

Run any tests defined in your policy. The file passed into this method should be written in Polar. CLI usage:


oso-cloud test main.polar

Note that this command is ephemeral: it won't persist the policy or any facts defined in the tests.

Talk to an Oso Engineer

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. We're happy to help.

Get started with Oso Cloud →