diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8beabf7 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,44 @@ +# Code of Conduct + +This project follows the [Contributor Covenant](https://www.contributor-covenant.org) Code of Conduct. + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our project and community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +- Demonstrating empathy and kindness +- Being respectful of differing viewpoints and experiences +- Giving and gracefully accepting constructive feedback +- Taking responsibility and apologizing to those affected by mistakes +- Focusing on what is best for the community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery +- Trolling, insulting, or derogatory comments +- Public or private harassment +- Publishing others’ private information without explicit permission +- Other conduct which could reasonably be considered inappropriate + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing this code of conduct and will take appropriate and fair corrective action in response to any behavior they deem inappropriate. + +## Reporting + +If you experience or witness unacceptable behavior, please report it via one of the following channels: + +- πŸ’¬ [Discord](https://discord.gg/HUVtY5gT6s) +- πŸ“§ [opensource@outscale.com](mailto:opensource@outscale.com) + +Reports will be handled confidentially and reviewed promptly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fdea9fc..fb56af1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,66 @@ -# Hacking Outscale SDK +# Contributing to oapi-cli -SDK itself is generated from Outscale's [COGNAC](https://github.com/outscale/COGNAC) using [osc-api](https://github.com/outscale/osc-api) description. +Thank you for considering contributing to **oapi-cli**! +We welcome contributions from everyoneβ€”whether it's reporting bugs, writing tests, improving documentation, or suggesting new features. -This mean that pull request providing change to code would be automatically overwritten in next [osc-api]. +--- + +## πŸ§‘β€πŸ’» How to Contribute + +### πŸ› Bug Reports + +- Clearly describe the issue. +- Include reproduction steps and environment details. +- If possible, provide a minimal failing example. + +### ✨ Feature Requests + +- Explain your use case. +- Provide context and expected behavior. +- Be open to feedback or refinement. + +### πŸ“˜ Documentation + +- Improvements to `README.md`, `variable.md`, or command examples are always helpful. +- Keep the tone consistent with other OUTSCALE projects. + +### πŸ§ͺ Tests + +- Adding tests to cover more scenarios is appreciated. + +--- + +## πŸ“¦ Pull Requests + +Please follow these guidelines: + +- Keep changes focused and scoped to a single purpose. +- Run the CLI and validate behavior before submitting. +- Use clear and descriptive commit messages. +- Link related issues in your PR description. + +> ⚠️ **Do not modify SDK-generated code manually. See below.** + +--- + +## 🧠 Hacking Outscale SDK + +The SDK used in this project is **generated automatically** using [Outscale's COGNAC](https://github.com/outscale/COGNAC) tool and the [osc-api](https://github.com/outscale/osc-api) specification. + +This means: + +- **Pull requests that change the generated SDK code will be overwritten** the next time we regenerate from `osc-api`. + +We **do** welcome contributions such as: + +- Feature suggestions +- CLI examples +- Documentation improvements +- Tests and usage validation + +--- + +## Questions? + +If you have any questions or need help, feel free to [open an issue](../../issues) or reach out to the maintainers on [Discord](https://discord.gg/HUVtY5gT6s). -Other contributions like examples, issue and tests are welcome! \ No newline at end of file diff --git a/README.md b/README.md index eab4de1..3b0182b 100644 --- a/README.md +++ b/README.md @@ -1,239 +1,278 @@ +# oapi-cli + [![Project Incubating](https://docs.outscale.com/fr/userguide/_images/Project-Incubating-blue.svg)](https://docs.outscale.com/en/userguide/Open-Source-Projects.html) +[![](https://dcbadge.limes.pink/api/server/HUVtY5gT6s?style=flat&theme=default-inverted)](https://discord.gg/HUVtY5gT6s) -# oapi-cli +

+ Terminal Icon +

-## Usage +--- -Get help: -```bash -oapi-cli --help # give help -``` +## 🌐 Links -Get DeleteTags help -``` -oapi-cli --help DeleteTags -``` +* πŸ“˜ Documentation: [Variable usage](./variable.md) +* πŸ§ͺ Nightly builds: [Latest AppImage](https://github.com/outscale/oapi-cli/releases/tag/nightly-linux) +* 🀝 Discussions & Feedback: [Discord](https://discord.gg/HUVtY5gT6s) -Examples of complex argument, with DeleteTags -[cascade notation](https://dart.dev/language/operators#cascade-notation): -```bash -oapi-cli DeleteTags --ResourceIds '["ID0", "ID1"]' --Tags.0.Key k0 ..Value v0 --Tags.1.Key k1 ..Value v1 -``` -Is the same as the line below but using [] syntax for `ResourceIds`, and without de argument, but in color. -```bash -oapi-cli --color DeleteTags --ResourceIds[] "ID0" --ResourceIds[] "ID1" --Tags.0.Key k0 --Tags.0.Value v0 --Tags.1.Key k1 --Tags.1.Value v1 -``` -and is the same as this below, using osc-cli-like notation -```bash -oapi-cli DeleteTags --ResourceIds '["ID0", "ID1"]' --Tags '[{"Key": "k0", "Value": "v0"}, {"Key": "k1", "Value": "v1"}]' -``` -On some shells (like zsh) using [] for arrays might not work. A workaround is to put singlequotes around the parameter -```bash -oapi-cli --color DeleteTags '--ResourceIds[]' "ID0" '--ResourceIds[]' "ID1" --Tags.0.Key k0 --Tags.0.Value v0 --Tags.1.Key k1 --Tags.1.Value v1 -``` +--- -show debug information (HTTP info, and json send to the api) -```bash -oapi-cli --verbose ReadVms -``` +## πŸ“„ Table of Contents -For complex argument, you can store argument in file using `--file`: -```bash -echo -n false > false.txt -./oapi-cli ReadVms --DryRun --file false.txt -``` -Here `-DryRun` argument will be "false", as it is what is inside false.txt. +* [Overview](#-overview) +* [Requirements](#-requirements) +* [Installation](#-installation) + * [macOS](#macos) + * [Linux](#linux) + * [Windows](#windows) +* [Usage](#-usage) -For CreatePolicy, you should use `--jsonstr-file`. + * [Command Syntax](#command-syntax) + * [Autocompletion](#autocompletion) + * [Variable System](#variable-system) +* [Configuration](#-configuration) -As CreatePolicy require Document to be a string contaning a jsons, if you want to pass the policy directly to oapi-cli, `--Document` argument should look like this: -``` -'{ \"Statement\": [ { \"Effect\": \"Allow\", \"Action\": [\"*\"], \"Resource\": [\"*\"] } ] }' -``` + * [Config File](#config-file) + * [Environment Variables](#environment-variables) +* [Notes](#-notes) +* [License](#-license) -With `--jsonstr-file`, you can simply create a json containing your policy, and pass it to oapi-cli: +--- -```bash -CreatePolicy --PolicyName please --Document --jsonstr-file ./policy.json -``` +## 🧭 Overview +**oapi-cli** is a command-line interface for interacting with OUTSCALE APIs. +It supports advanced argument syntax, response chaining, JSON file inputs, and a built-in variable system to streamline complex workflows. -*Note that with osc-cli, you need to add `api`, here, as we only support outscale api, this is remove* +The CLI is fully self-contained, with prebuilt packages for Linux (AppImage), macOS (Homebrew), and Windows (zip archive). -# Autocompletion +--- + +## βœ… Requirements + +* Outscale API access (AK/SK or login/password) +* Config file or environment variables for authentication +* AppImage support (Linux only, see notes if FUSE is not installed) + +--- + +## πŸ’» Installation + +### macOS -Bash autocompletion is avaible using either ```bash -source <(oapi-cli-x86_64.AppImage --bash-completion) +brew tap outscale/tap +brew install outscale/tap/oapi-cli ``` -With the appimage -or sourcing `oapi-cli-completion.bash` file -For zsh, you might need to create a file like: -```zsh -user@machine-on-zsh ~ % cat ~/oapi-cli-completion.zsh -``` -``` -autoload bashcompinit -bashcompinit -source $HOME/oapi-cli-completion.bash -``` +Or manually: -If it is not in your .zshrc, you might need to add this line too: -``` -autoload -Uz compinit && compinit +```bash +git clone https://github.com/outscale/homebrew-tap +cd homebrew-tap +brew install Formula/oapi-cli.rb ``` -# oapi-cli Variables +--- +### Linux -oapi-cli offer its own "variables" system. -They can be use if you want to chain calls. -For example, let's say you want a Vm call "my vm". -If you want to set "my vm" as a name, you would normally require to first call CreateVms. -Then get the VmId, and use that VmId with CreateTag. +Download the AppImage from the [nightly build](https://github.com/outscale/oapi-cli/releases/tag/nightly-linux). -This is particularly cumbersome in a script, as you need to parse CreateVm output manually to get VmId. +```bash +chmod a+x ./oapi-cli-x86_64.AppImage +./oapi-cli-x86_64.AppImage +``` + +Optional installation: + +```bash +sudo mv oapi-cli-x86_64.AppImage /usr/local/bin/oapi-cli +``` -But as oapi-cli allow to chain calls, having a way, to keep some argument taken from a Call return, and send it to the next call, enable us to make a vm with a name, in only one oapi-cli command. +**Note:** If you see FUSE-related errors, use: -To do so, here's how to do it using oapi-cli's variables: -```sh -oapi-cli CreateVms --ImageId IMG_NAME --set-var vm_id=Vms.0.VmId \ -CreateTags --ResourceIds[] --var vm_id --Tags.0.Key Name ..Value "my vm" +```bash +./oapi-cli-x86_64.AppImage --appimage-extract-and-run ReadImages ``` -Here `VmId` is store in `vm_id` oapi-cli variable using `--set-var vm_id=Vms.0.VmId`, and then used in CreateTags, with `-var vm_id` argument. +--- -`--set-var`, take a single argument, a string using the syntax `ID=JSON_PATH`. -In order to use it, you need to know which part of a call return you want to store in a variable. +### Windows -more examples [here](./variable.md) +Download `oapi-cli-x86_64-windows.zip` from [Releases](https://github.com/outscale/oapi-cli/releases/latest). +Extract and run `oapi-cli.exe`. -# Config +> ⚠️ Config is read from `.\config.json` in the current directory. -## using `~/.osc/config.json` on unix/macOS, or .\config.json on windows +--- -``` -{"default": - {"access_key": "MYACCESSKEY", - "secret_key": "MYSECRETKEY", - "region": "eu-west-2" - }, - "us": - {"access_key": "MYACCESSKEY", - "secret_key": "MYSECRETKEY", - "region": "us-east-2" - } -} +## πŸš€ Usage + +### 🧾 Command Syntax + +```bash +oapi-cli [OPTIONS] ``` -avaible option for the profile are: -`access_key`, `secret_key`, `region`, `x509_client_cert`, `client_certificate`, `x509_client_sslkey`, `proxy`, `endpoints` and `endpoint`. +Get general help: +```bash +oapi-cli --help +``` -`x509_client_cert` and `client_certificate` are the same. +Get help for a specific operation: -`endpoint` take the endpoints directly (example: `"endpoint": "https://120.0.0.1:3000"`) +```bash +oapi-cli --help DeleteTags +``` -where `endpoints` take an object. (example: `"endpoints: {"api": "https://120.0.0.1:3000"}"`) +### Examples -## Environement Variables +#### Complex arguments -AK/SK: ```bash -export OSC_ACCESS_KEY=ACCESS_KEY -export OSC_SECRET_KEY=SECRET_KEY +oapi-cli DeleteTags --ResourceIds '["ID0", "ID1"]' --Tags '[{"Key": "k0", "Value": "v0"}, {"Key": "k1", "Value": "v1"}]' ``` -LOGIN/PASSWORD: +Alternative syntax: + ```bash -export OSC_LOGIN=LOGIN -export OSC_PASSWORD=PASSWORD +oapi-cli --color DeleteTags \ + --ResourceIds[] "ID0" --ResourceIds[] "ID1" \ + --Tags.0.Key k0 --Tags.0.Value v0 \ + --Tags.1.Key k1 --Tags.1.Value v1 ``` -Region: +Zsh workaround (for brackets): + ```bash -export OSC_REGION=REGION # default is eu-west-2 +oapi-cli --color DeleteTags '--ResourceIds[]' "ID0" '--ResourceIds[]' "ID1" ... ``` -Profile: +Verbose mode: + ```bash -export OSC_PROFILE=my_profile #default is 'default' +oapi-cli --verbose ReadVms ``` -Endpoint: +Use `--file` to pass argument from a file: + ```bash -export OSC_ENDPOINT_API=XXX +echo -n false > false.txt +oapi-cli ReadVms --DryRun --file false.txt ``` -## installing on Macos +### CreatePolicy with JSON string ```bash -brew tap outscale/tap -brew install outscale/tap/oapi-cli +oapi-cli CreatePolicy --PolicyName please \ + --Document --jsonstr-file ./policy.json ``` -or if you want to clone the homebrew repo: + +--- + +## 🧩 Autocompletion + +### Bash ```bash -git clone https://github.com/outscale/homebrew-tap -cd homebrew-tap -brew install Formula/oapi-cli.rb +source <(oapi-cli-x86_64.AppImage --bash-completion) ``` -## Installing on Linux +Or source `oapi-cli-completion.bash`. -oapi-cli is pre-packaged for Linux as a standalone AppImage. -Download oapi-cli-x86_64.AppImage from [nightly build](https://github.com/outscale/oapi-cli/releases/tag/nightly-linux). -Allow file to be executed by running -`chmod a+x ./oapi-cli-x86_64.AppImage` +### Zsh -Run oapi-cli: `./oapi-cli-x86_64.AppImage` +```zsh +autoload bashcompinit +bashcompinit +source ~/oapi-cli-completion.bash -Optionally, you can install it for all users: -```sh -sudo mv oapi-cli-x86_64.AppImage /usr/local/bin/oapi-cli +autoload -Uz compinit && compinit # if not already in .zshrc ``` -and run `oapi-cli`. (as long as /usr/local/bin/ is in your PATH environement variable) -if you have this error (or one similar about fuse): +--- +## πŸ” Variable System + +oapi-cli supports internal variables between chained calls. + +```bash +oapi-cli CreateVms --ImageId IMG_ID --set-var vm_id=Vms.0.VmId \ + CreateTags --ResourceIds[] --var vm_id --Tags.0.Key Name ..Value "my vm" ``` -fuse: failed to exec fusermount: No such file or directory -Cannot mount AppImage, please check your FUSE setup. -See https://github.com/AppImage/AppImageKit/wiki/FUSE -for more information -open dir error: No such file or directory -``` -You might still be able to extract the contents of this AppImage if you run it with the `--appimage-extract` option. -You can either install fuse yourself, or execute the appimage with `--appimage-extract-and-run` option +This captures the `VmId` from the first call and reuses it in the second. + +More examples in [variable.md](./variable.md) + +--- + +## πŸ›  Configuration + +### πŸ“„ Config File + +Located at: + +* Unix/macOS: `~/.osc/config.json` +* Windows: `.\\config.json` (same folder as binary) Example: + +```json +{ + "default": { + "access_key": "MYACCESSKEY", + "secret_key": "MYSECRETKEY", + "region": "eu-west-2" + }, + "us": { + "access_key": "MYACCESSKEY", + "secret_key": "MYSECRETKEY", + "region": "us-east-2" + } +} ``` -./oapi-cli-x86_64.AppImage --appimage-extract-and-run ReadImages -``` -using appimage-extract-and-run extract the content of the AppImage in a temporary directory and execute it, this operation is a lot slower than using fuse, and the fuse solution should be use if posible. +Supported keys: `access_key`, `secret_key`, `region`, `x509_client_cert`, `client_certificate`, `x509_client_sslkey`, `proxy`, `endpoint`, `endpoints` + +--- -## Arch Linux -you can also install oapi-cli-git on Arch Linux using AUR: (yay -S oapi-cli-git) +### 🌍 Environment Variables -## Windows +```bash +# AK/SK authentication +export OSC_ACCESS_KEY=... +export OSC_SECRET_KEY=... + +# Login/password authentication +export OSC_LOGIN=... +export OSC_PASSWORD=... + +# Region (default: eu-west-2) +export OSC_REGION=... + +# Profile +export OSC_PROFILE=default + +# Override endpoint +export OSC_ENDPOINT_API=https://... +``` -oapi-cli is pre-packaged for Widows as a zip archive. +--- -Download oapi-cli-x86_64-windows.zip from [release pages](https://github.com/outscale/oapi-cli/releases/latest). +## πŸ“ Notes -Extract it, run `oapi-cli`. +* The CLI supports multiple argument styles (cascaded, OSC-style, JSON). +* SDK is generated from [COGNAC](https://github.com/outscale/COGNAC) using [osc-api](https://github.com/outscale/osc-api). +* If AppImage FUSE fails, try `--appimage-extract-and-run`. -Note: in comparaison to linux and macos packages, windows oapi-cli look for the config in the directory where it is run. -(so config path is .\config.json) +--- +## πŸ“œ License -# Feedback -Either open a github issue, or post a message here: https://github.com/outscale/oapi-cli/discussions/10 +**oapi-cli** is licensed under BSD-3-Clause. -# Notes -SDK itself is generated from Outscale's [COGNAC](https://github.com/outscale/COGNAC) using [osc-api](https://github.com/outscale/osc-api) description. +Β© Outscale SAS diff --git a/variable.md b/variable.md index f1f4d70..cdadcfc 100644 --- a/variable.md +++ b/variable.md @@ -1,20 +1,31 @@ +# 🧩 Using Variables in `oapi-cli` -Let's say you want to create a VM, called "joe" in a script. +`oapi-cli` introduces a powerful variable system that allows you to **chain multiple API calls in a single command**. This removes the need to manually parse output with tools like `jq` and simplifies scripting. -using osc-cli, you would have to do something like this: +--- + +## πŸ–Ό Example: Creating a VM with a Name Tag + +### 🧱 Traditional approach (osc-cli + jq) + +To create a VM named "foo" using `osc-cli`, you'd need to extract the `VmId` manually: ```sh vm_id=$(osc-cli api CreateVms --ImageId $id | jq .Vms[0].VmId) -oapi-cli CreateTags --ResourceIds "[$vm_id]" --Tags '[ { "Key": "Name", "Value": "joe" } ]' +oapi-cli CreateTags --ResourceIds "[$vm_id]" --Tags '[ { "Key": "Name", "Value": "foo" } ]' ``` -Moreover if you want to retrieve the ImageId programmatically, You need another call to ReadImage: + +If you also want to retrieve the `ImageId` dynamically: + ```sh image_id=$(osc-cli api ReadImages --Filters '{"ImageNames": ["RockyLinux*"]}' | jq .Images[0].ImageId) vm_id=$(osc-cli api CreateVms --ImageId $image_id | jq .Vms[0].VmId) -oapi-cli CreateTags --ResourceIds "[$vm_id]" --Tags '[ { "Key": "Name", "Value": "joe" } ]' +oapi-cli CreateTags --ResourceIds "[$vm_id]" --Tags '[ { "Key": "Name", "Value": "foo" } ]' ``` -With oapi-cli you can now chain calls, so you don't have to keep intermediary variables. +--- + +### βœ… oapi-cli with chained calls and variables ```sh oapi-cli ReadImages --Filter.ImageNames[] "RockyLinux*" --set-var img_id=Images.0.ImageId \ @@ -22,7 +33,15 @@ oapi-cli ReadImages --Filter.ImageNames[] "RockyLinux*" --set-var img_id=Images. CreateTags --ResourceIds[] --var vm_id --Tags.0.Key Name ..Value "my vm" ``` -New let's create a Net, a SecurityGroups, and add rule on it. +βœ… No need for intermediate shell variables or `jq` +βœ… Easier to read and write +βœ… All in one command + +--- + +## πŸ–Ό Example: Creating a Net, Security Group, and Rule + +### 🧱 Traditional approach (osc-cli + jq) ```sh net=$(osc-cli --endpoint "http://127.0.0.1:3000" api CreateNet --IpRange "10.0.0.0/16" | jq .Net.NetId) @@ -36,22 +55,39 @@ osc-cli --endpoint "http://127.0.0.1:3000" api CreateSecurityGroupRule \ --Flow "Inbound" \ --SecurityGroupId $sg \ --Rules '[ - { - "FromPortRange": 22, - "ToPortRange": 22, - "IpProtocol": "tcp", - "SecurityGroupsMembers": [{"AccountId": "123456789012", "SecurityGroupName": "another-security-group"}], - }, - ]' + { + "FromPortRange": 22, + "ToPortRange": 22, + "IpProtocol": "tcp", + "SecurityGroupsMembers": [ + { "AccountId": "123456789012", "SecurityGroupName": "another-security-group" } + ] + } + ]' ``` -with oapi-cli +--- + +### βœ… oapi-cli with variables + ```sh -oapi-cli CreateNet --IpRange "10.0.0.0/16" --set-var net=Net.NetId \ - CreateSecurityGroup --NetId --var net --SecurityGroupName "security-group-example"\ - --Description "Security group example" --set-var sg=SecurityGroup.SecurityGroupId \ +oapi-cli CreateNet --IpRange "10.0.0.0/16" --set-var net=Net.NetId \ + CreateSecurityGroup --NetId --var net \ + --SecurityGroupName "security-group-example" \ + --Description "Security group example" --set-var sg=SecurityGroup.SecurityGroupId \ CreateSecurityGroupRule --Flow "Inbound" --SecurityGroupId --var sg \ --Rules.0.FromPortRange 22 ..ToPortRange 22 ..IpProtocol tcp \ ..SecurityGroupsMembers.0.AccountId 123456789012 \ ..SecurityGroupName another-security-group ``` + +--- + +## 🧠 How It Works + +* `--set-var NAME=JSON_PATH`: stores a value from a response using a dot-separated JSON path. +* `--var NAME`: uses a previously stored variable as argument value. +* `..` is shorthand to reuse the same object prefix for multiple keys (`--Tags.0.Key`, `..Value`). + +> Variables are scoped **within the same command chain**. +