📝 docs: Rewrite README; move detailed information into docs/ 🚚

Author: outscale-rce

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).

README.md

@@ -1,242 +1,77 @@
 [![Project Graduated](https://docs.outscale.com/fr/userguide/_images/Project-Graduated-green.svg)](https://docs.outscale.com/en/userguide/Open-Source-Projects.html)
-
-# Outscale CLI
-
-Official Outscale CLI providing connectors to Outscale API.
-
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![](https://dcbadge.limes.pink/api/server/HUVtY5gT6s?style=flat&theme=default-inverted)](https://discord.gg/HUVtY5gT6s)
 
-## Maintenance mode !
-
-This project is now in maintenance mode, we will still fix bugs here, but no new features will be work on.
-If you want new features, you should use [oapi-cli](https://github.com/outscale/oapi-cli),
-which support all of osc-api, and have some syntax suggar to ease complex argument manipulation in comparaison to osc-cli usage.
-
-## Getting Started
-
-
-### Installing on Macos
-
-osc-cli is available on [brew](https://formulae.brew.sh/formula/osc-cli).
-
-### Installing on Linux
-
-osc-cli is pre-packaged for Linux as a standalone [AppImage](https://appimage.org/).
-- Download `osc-cli-x86_64.AppImage` from latest version in [releases](https://github.com/outscale/osc-cli/releases).
-- Allow file to be executed by running `chmod a+x osc-cli-x86_64.AppImage`
-- Run osc-cli: `./osc-cli-x86_64.AppImage`
-
-Optionally, you can install it for all users: `sudo mv osc-cli-x86_64.AppImage /usr/local/bin/osc-cli` and just run `osc-cli`.
-
-you can also install `osc-cli-git` on Arch Linux using AUR: (`yay -S osc-cli-git`)
-
-#### Note:
-
-if you have this error (or one similar about fuse):
-```
-fuse: failed to exec fusermount: No such file or directory
-
-Cannot mount AppImage, please check your FUSE setup.
-You might still be able to extract the contents of this AppImage
-if you run it with the --appimage-extract option.
-See https://github.com/AppImage/AppImageKit/wiki/FUSE
-for more information
-open dir error: No such file or directory
-```
-
-You can either install fuse yourself, or execute the appimage with `--appimage-extract-and-run` option
-
-Example:
-```
-./osc-cli-x86_64.AppImage --appimage-extract-and-run osc-cli api ReadImages --profile=my
-```
-
-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.
-
-
-### Installing on Windows
-
-[Check dedicated documentation](windows-setup.md) regarding windows installation.
+<p align="center">
+  <img alt="Terminal Icon" src="https://img.icons8.com/ios-filled/100/console.png" width="100px">
+</p>
 
-### Installing from Python package
+# Outscale CLI (osc-cli)
 
-#### Prerequisites
+Official command-line interface for the OUTSCALE API.
 
-You will need [Python 3.6+](https://www.python.org/) or later. Earlier versions including Python 2 are not supported.
-
-#### Pip
-
-You can get the package from [pypi](https://pypi.org/project/osc-sdk/):
-```
-pip3 install osc-sdk
-```
+> **Maintenance mode**: bug fixes only; no new features.  
+> Looking for new features and an improved UX? See **[oapi-cli](https://github.com/outscale/oapi-cli)**.
 
-If you are using Microsoft Windows, see [how to setup osc-cli on Windows](windows-setup.md).
+## Quick start
 
-### Installing from sources
+**macOS (Homebrew)**
+```bash
+brew install osc-cli
+````
 
-It is a good practice to create a [dedicated virtualenv](https://virtualenv.pypa.io/en/latest/) first. Even if it usually won't harm to install Python libraries directly on the system, better to contain dependencies in a virtual environment.
+**Linux (AppImage)**
 
 ```bash
-python3 -m venv .venv
-source .venv/bin/activate
+# get the latest release from GitHub
+chmod a+x osc-cli-x86_64.AppImage
+./osc-cli-x86_64.AppImage
+# (optional) sudo mv osc-cli-x86_64.AppImage /usr/local/bin/osc-cli
 ```
 
-Then install osc-cli in your virtual env:
+**Python package**
+
 ```bash
-pip install -e .
+pip3 install osc-sdk
 ```
 
-## Configure osc-cli
+**Windows**
+See [docs/install/windows.md](docs/install/windows.md).
 
-The CLI requires a configuration file in `~/.osc/config.json` The content must be a JSON whose contents look like this:
-/!\ the old configuration path using `.osc_sdk` folder is **deprecated**. Please use the new one with `.osc`.
-```json
-{"default":
-    {"access_key": "MYACCESSKEY",
-     "secret_key": "MYSECRETKEY",
-     "region": "eu-west-2"
-    },
-  "us":
-    {"access_key": "MYACCESSKEY",
-     "secret_key": "MYSECRETKEY",
-     "host": "outscale.com",
-     "https": true,
-     "method": "POST",
-     "region": "us-east-2"
-    }
-}
-```
-You can add several profiles for different regions or users.
+## Minimal configuration
 
-Optional parameters can be applied to each profile :
-* client_certificate: if you need additional security, your pem must include your private key and your certificate
-* version: if you want to query another version of the API
+Create `~/.osc/config.json`:
 
 ```json
-{"default":
-    {"access_key": "MYACCESSKEY",
-     "secret_key": "MYSECRETKEY",
-     "client_certificate" : "path_to_your_pem",
-     "host": "outscale.com",
-     "https": true,
-     "method": "POST",
-     "region": "eu-west-2",
-     "version": "2018-11-19"
-    }
+{
+  "default": {
+    "access_key": "MYACCESSKEY",
+    "secret_key": "MYSECRETKEY",
+    "region": "eu-west-2"
+  }
 }
 ```
 
-## Get osc-cli version
-
-`--version` option will print osc-cli version and exit.
-```
-osc-cli --version
-```
-
-## Activate bash-completion
-
-### Activate the completion for the current bash session
-
-```
-source <(osc-cli --bash_completion)
-```
-
-### Generate the file to add it in your bach rc:
-```
-osc-cli --bash_completion > ~/.osc/cli-completion.bash
-```
-then in your bashrc add:
-
-```
-source ~/.osc/cli-completion.bash
-```
-
 ## Usage
 
-```
-osc-cli SERVICE CALL [PROFILE] [CALL-PARAMETERS]
-```
-or
-```
-osc-cli --service SERVICE --call CALL [PROFILE] [--CALL_PARAMS ...]
-```
-with
-* SERVICE one of the [services](http://docs.outscale.com) provided by Outscale (`fcu`, `lbu`, `icu`, `eim`, `directlink`, `okms` and `api`)
-* CALL the call you request (ie ReadVms, DescribeInstances...)
-* PROFILE the profile you want to connect to (optional)
-* CALL_PARAMS call arguments which are case-sensitive (optional)
-
-
-Here is an example of a simple volume creation:
 ```bash
-osc-cli fcu CreateVolume --AvailabilityZone eu-west-2a --Size 10
-{
-    "CreateVolumeResponse": {
-        "@xmlns": "http://ec2.amazonaws.com/doc/2014-06-15/",
-        "requestId": "508f428a-9fd8-4a49-9fe6-d0bf311de3b4",
-        "volumeId": "vol-6a2aa442",
-        "size": "10",
-        "snapshotId": null,
-        "availabilityZone": "eu-west-2a",
-        "status": "creating",
-        "createTime": "2019-01-17T12:53:57.836Z",
-        "volumeType": "standard"
-    }
-}
+osc-cli SERVICE CALL [PROFILE] [CALL-PARAMETERS]
+# example:
+osc-cli api ReadVms
 ```
 
-Be careful with your quotes ! If you want to pass the string `"12345678"` rather than the integer `12345678` you'll need to quote your quotes:
-```bash
-$ osc-cli icu CreateAccount --Email "example@email.com" \
-			    --FirstName "Osc" \
-			    --LastName "Cli" \
-			    --Password "12345toto" \
-			    --ZipCode '"92000"' \
-			    --Country "France" \
-			    --CustomerId '"12345678"'
-```
+## Documentation
 
-Another example with an array of strings into args:
-```bash
-$ osc-cli api CreateDhcpOptions --DomainName="toot.toot" \
-				--DomainNameServers="['1.1.1.1']" \
-				--NtpServers="['1.1.1.1']"
-```
+* Installation guides (macOS, Linux/AppImage, Windows, pip, source): [docs/install/](docs/install/)
+* Configuration and profiles: [docs/configuration.md](docs/configuration.md)
+* Usage and argument parsing: [docs/usage.md](docs/usage.md), [docs/argument-parsing.md](docs/argument-parsing.md)
+* Shell completion: [docs/completion.md](docs/completion.md)
+* Troubleshooting & FAQ: [docs/troubleshooting.md](docs/troubleshooting.md)
 
-Example with a complex structure:
-```bash
-osc-cli icu CreateListenerRule \
---Instances '[{"InstanceId": "i-12345678"}]' \
---ListenerDescription '{"LoadBalancerName": "osc", "LoadBalancerPort": 80}'
---ListenerRuleDescription '{"RuleName": "hello", "Priority": 100, "PathPattern": "/"}'
-```
-
-**Argument Parsing**
-```bash
-$ osc-cli api example --obj=[1,2]    	# list
-$ osc-cli api example --obj=10		# int
-$ osc-cli api example --obj="10"	# int
-$ osc-cli api example --obj="'10'"	# str
-$ osc-cli api example --obj=\"10\"	# str
-
-$ osc-cli api example --obj="hello"	# str
-$ osc-cli api example --obj=hello	# str
-```
-**Warning** if you're adding a list which contain strings with specifics characteres, there is a workaround:
-```bash
-$ osc-cli api example --obj="['vol-12345678', 'vol-87654322']"    	# list
-```
+## Contributing
 
-## Authentication
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-You API crendentials are composed of an Access Key and a Secret Key located in `.osc_sdk/config.json`.
-You can list you access keys using your user and password:
-```bash
-osc-cli icu ListAccessKeys --authentication-method=password --login youremail@company.com --password=Y0URpAssOrd
-```
-## Contributing
-OSC-CLI is an **open source software** licensed under **BSD-3-Clause.**
+## License
 
-Patches and discussions are welcome about bugs you've found or features you think are missing. If you would like to help making **osc-cli** better, take a look to [CONTRIBUTING.md](https://github.com/outscale/osc-cli/blob/master/CONTRIBUTING.md) file.
+BSD-3-Clause. See [LICENSE](LICENSE).

docs/argument-parsing.md

@@ -0,0 +1,31 @@
+# Argument parsing and quoting
+
+Passing strings vs integers:
+```bash
+# pass "12345678" (string) instead of 12345678 (int)
+osc-cli icu CreateAccount   --Email "example@email.com" --FirstName "Osc" --LastName "Cli" --Password "12345toto"   --ZipCode '"92000"'   --Country "France"   --CustomerId '"12345678"'
+```
+
+Arrays of strings:
+```bash
+osc-cli api CreateDhcpOptions --DomainName="toot.toot" --DomainNameServers="['1.1.1.1']" --NtpServers="['1.1.1.1']"
+```
+
+Complex structures:
+```bash
+osc-cli icu CreateListenerRule --Instances '[{"InstanceId": "i-12345678"}]' --ListenerDescription '{"LoadBalancerName": "osc", "LoadBalancerPort": 80}' --ListenerRuleDescription '{"RuleName": "hello", "Priority": 100, "PathPattern": "/"}'
+```
+
+Type hints:
+```bash
+osc-cli api example --obj=[1,2]     # list
+osc-cli api example --obj=10        # int
+osc-cli api example --obj="10"      # int
+osc-cli api example --obj="'10'"    # str
+osc-cli api example --obj=\"10\"    # str
+
+osc-cli api example --obj="hello"   # str
+osc-cli api example --obj=hello     # str
+# If your list contains strings with special characters:
+osc-cli api example --obj="['vol-12345678', 'vol-87654322']"  # list
+```

docs/authentication.md

@@ -0,0 +1,8 @@
+# Authentication
+
+Credentials live in `~/.osc/config.json` under your profiles.
+
+List your access keys using login/password:
+```bash
+osc-cli icu ListAccessKeys --authentication-method=password --login youremail@company.com --password Y0URpAsswOrd
+```

docs/completion.md

@@ -0,0 +1,13 @@
+# Shell completion (bash)
+
+Activate for the current shell:
+```bash
+source <(osc-cli --bash_completion)
+```
+
+Persist it:
+```bash
+osc-cli --bash_completion > ~/.osc/cli-completion.bash
+# then in your ~/.bashrc
+source ~/.osc/cli-completion.bash
+```