Command-Line Interface (CLI)

ℹ️

For changes to the Oso Cloud CLI, see Changelog.

Set up the Oso Cloud CLI

Install the Oso Cloud CLI package

To install the Oso Cloud CLI, run the following command:


$ curl -L https://cloud.osohq.com/install.sh | bash

You can verify the installation succeeded using:


which oso-cloud

Configure the CLI

When you use the CLI, it connects to one of your account's environments.

To configure the CLI to use a specific environment:

Create or find an API key for the environment you want to use (opens in a new tab).
Export the API key as OSO_AUTH:

export OSO_AUTH=<your_oso_api_key>

Centralized Authorization Data API

Oso Cloud clients provide an API to manage authorization data stored directly in Oso Cloud.

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

The Check API lets you provide context facts with each request. When Oso Cloud performs a check, it considers the request's context facts in addition to any other centralized authorization data. Context facts are only used in the API call in which they're provided-- they do not persist across requests.

For more details, see Context Facts.

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.

Local Check API

The local check API lets you perform authorization using data that's distributed across Oso Cloud and your own database.

For more information, see Local Authorization.

Validate Local Authorization config: `oso-cloud validate-local-authorization-config <config-file> -c <connection-string> -p <policy-file>`

Validate a Local Authorization config: the YAML file that specifies how to resolve facts in your database.

When a connection string is set, runs each SQL query in the config_file against the PostgreSQL database to ensure they are valid, and ensures the queries' SQL types match the types in the sql_types section of the config.

When a policy is set, validates that the configured facts are consistent with the Polar policy.


oso-cloud validate-local-authorization-config path/to/local_authorization_config.yaml -c postgres://localhost -p main.polar

List authorized resources with local data: `oso-cloud list-local --data-bindings <config-file> <actor> <action> <resource-type> <column>`

Fetches a filter that can be applied to a database query to return just the resources on which an actor can perform an action. Example:


oso-cloud list-local --data-bindings path/to/local_authorization_config.yaml User:alice read Issue id

Check a permission with local data: `oso-cloud authorize-local --data-bindings <config-file> <actor> <action> <resource>`

Fetches a query that can be run against your database to determine whether an actor can perform an action on a resource. Example:


oso-cloud list-local --data-bindings path/to/local_authorization_config.yaml User:alice read Issue:swage

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.

Force

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.

Preview changes

To preview a policy change (without submitting it), pass the --preview flag:


oso-cloud policy main.polar --preview
Previewing policy changes.
4   4    |    permissions = ["read"];
5   5    |
6   6    |    "read" if "member";
    7    |+   "member" if "admin";
7   8    | }
8   9    |
9   10   | resource Bar {
10       |-   roles = ["admin", "member"];
    11   |+   roles = ["admin", "memberz"];
11  12   | }
12  13   |
Running policy tests.
Ran 0 tests:
PASS

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 →

Windows

Command-Line Interface (CLI)

Set up the Oso Cloud CLI

Install the Oso Cloud CLI package

Configure the CLI

Centralized Authorization Data API

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

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

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

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

Check API

Context facts

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

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

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

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

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

Local Check API

Validate Local Authorization config: oso-cloud validate-local-authorization-config <config-file> -c <connection-string> -p <policy-file>

List authorized resources with local data: oso-cloud list-local --data-bindings <config-file> <actor> <action> <resource-type> <column>

Check a permission with local data: oso-cloud authorize-local --data-bindings <config-file> <actor> <action> <resource>

Policy API

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

Force

Preview changes

Multiple policies

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

Talk to an Oso engineer

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

Delete fact: `oso-cloud delete <predicate> ({_, <type>}:{_, <id>} )*`

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

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

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

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

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

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

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

Validate Local Authorization config: `oso-cloud validate-local-authorization-config <config-file> -c <connection-string> -p <policy-file>`

List authorized resources with local data: `oso-cloud list-local --data-bindings <config-file> <actor> <action> <resource-type> <column>`

Check a permission with local data: `oso-cloud authorize-local --data-bindings <config-file> <actor> <action> <resource>`

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

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