Comparison Between OSC CLI and oapi-cli

This page presents the main differences between OSC CLI and oapi-cli, in order to familiarize yourself with the latter or help you migrate your scripts from the former to the latter.

API Support

OSC CLI enables you to send requests to the OUTSCALE API and most of our AWS-compliant APIs.

On the other hand, oapi-cli supports the OUTSCALE API exclusively as it is dedicated to providing first-class support to it.

Therefore, if you do not need to use the AWS-compliant APIs, you can fully migrate to oapi-cli. If you need to use the AWS-compliant APIs, you will still need OSC CLI. Both CLIs can co-exist on the same machine.

For more information on the APIs provided by OUTSCALE, see About the APIs.

Maturity Level

OSC CLI is the historical command-line interface for OUTSCALE. It is now in maintenance mode, meaning bugs are still fixed for it but no new features are added to it.

oapi-cli is the newer command-line interface for OUTSCALE, providing expanded features and improved user experience. oapi-cli currently has a maturity level of Incubating according to the classification of our Open Source Projects.

Features Exclusive to oapi-cli

Handling of Error Responses

With oapi-cli, if you receive an error response from the API, the JSON error object is cleanly parsed and printed in your terminal. This differs from OSC CLI, which, as a CLI written in Python, only prints a Python traceback in your terminal.

In both cases, the List of OUTSCALE API Errors page remains useful to find additional descriptions of the errors.

Bash Autocompletion

oapi-cli provides a Bash autocompletion feature. For more information, see the README on GitHub.

Variable System

oapi-cli provides a pseudo-variable system which enables you to chain several commands while dynamically using values from received responses. For more information, see the README on GitHub.

Differences in Syntaxes Between OSC CLI and oapi-cli

Overview

The default syntaxes of the two CLIs are similar, so migrating from one to the other does not require complex rewriting. In most cases, rewriting an OSC CLI command for oapi-cli only involves replacing osc-cli api with oapi-cli at the start of the command:

$ osc-cli api ReadVolumes --Filters '{ "VolumeStates": ["in-use"] }'
$ oapi-cli ReadVolumes --Filters '{ "VolumeStates": ["in-use"] }'

oapi-cli also provides alternate ways to specify the parameter values, especially for nested parameters, but these are completely optional. For more information, see Installing and Configuring oapi-cli > Using Alternate Syntaxes.

The sections below present the few actually notable differences that you need to consider when migrating to oapi-cli.

Order of the Options

Historically, the OSC CLI examples in this documentation have put the authentication options (such as --profile) after the name of the call, but you can also put them before it, separate from the call’s request parameters (in the following example, --Filters):

$ osc-cli api ReadVolumes --profile "default" --Filters '{ "VolumeStates": ["in-use"] }'
$ osc-cli --profile "default" api ReadVolumes --Filters '{ "VolumeStates": ["in-use"] }'

With oapi-cli however, you have to put the authentication options before the name of the call:

$ oapi-cli --profile "default" ReadVolumes --Filters '{ "VolumeStates": ["in-use"] }'

Booleans

With OSC CLI, booleans need to start with a capital letter, due to OSC CLI being written in Python:

--DryRun True

With oapi-cli, booleans are case-insensitive:

--DryRun true

Numerical Strings

With OSC CLI, if you want to specify a number as a string, rather than as an integer (for example in CreateNetPeering), you must wrap it in two pairs of quotes:

--AccepterOwnerId '"123456789012"'

With oapi-cli, numerical strings are correctly recognized:

--AccepterOwnerId "123456789012"

JSON Strings

With OSC CLI, if you want to specify JSON data as a string (for example in CreatePolicy), you must escape this data:

--Document '"{\"Statement\": [ {\"Effect\": \"Allow\", \"Action\": [\"*\"], \"Resource\": [\"*\"]} ]}"'

With oapi-cli, the best practice is to write your JSON data in a file and pass it with the --jsonstr-file argument:

--Document --jsonstr-file "policy.json"

Certificate Strings

With OSC CLI, if you want to specify a certificate as a string (for example in CreateCa), the recommended way is to use a Shell command substitution:

--CaPem="$(cat ca-certificate.pem)"

With oapi-cli, the best practice is to pass the content of the certificate file by using the --file argument:

--CaPem --file "ca-certificate.pem"

Related Pages

AWS™ and Amazon Web Services™ are trademarks of Amazon Technologies, Inc or its affiliates in the United States and/or other countries.

Export to PDF