diff --git a/README.md b/README.md
index b8a8b68..1403c99 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-# @frsource/frs-replace
-
+
@@ -12,51 +11,68 @@
-
-[](https://www.npmjs.com/package/@frsource/frs-replace)
-[](https://github.com/semantic-release/semantic-release)
-[](https://coveralls.io/github/FRSource/frs-replace?branch=master)
-[](https://codebeat.co/projects/github-com-frsource-frs-replace-master)
-
-The fastest ([see benchmarks](#chart_with_upwards_trend-benchmarks)) CLI & Node wrapper around [javascript replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) which allows in-file replacing (with possibility to save changed file as a copy), [globbing](), [piping]() and many more!
-
-- [:scroll: Installation](#scroll-installation)
-- [:keyboard: CLI](#keyboard-cli)
-- [:mag_right: Examples and recipes - CLI](#mag_right-examples-and-recipes---cli)
-- [:books: Node API](#books-node-api)
-- [:mag_right: Examples and recipes - Node](#mag_right-examples-and-recipes---node)
-- [:chart_with_upwards_trend: Benchmarks](#chart_with_upwards_trend-benchmarks)
+
+
+@frsource/frs-replace - replace content directly in your files/streams with ease (CLI included)! 📝
+
+
+ File an Issue
+ ·
+ Question or an idea?
+ ·
+ Benchmarks
+
+
+
+The fastest (see benchmarks) CLI & Node wrapper around javascript replace which allows in-file replacing (with possibility to save changed file as a copy), globbing, piping and many more!
+
+
+ Getting Started (CLI)
+ ·
+ Examples and recipes (CLI)
+
+ Getting Started (Node)
+ ·
+ Examples and recipes (Node)
+
+
## :scroll: Installation
```bash
npm install @frsource/frs-replace
-yarn add @frsource/frs-replace
-pnpm install @frsource/frs-replace
```
or execute it right away:
```bash
npx @frsource/frs-replace
-yarn dlx @frsource/frs-replace
-pnpx @frsource/frs-replace
```
## :keyboard: CLI
```bash
-frs-replace [options]
+frs-replace [flags]
+```
+
+Basic usage:
+
+```bash
+frs-replace something anything -i foo.js -o foo_replaced.js
+
+# all of the occurences of "something" in `foo.js` will be replaced with "anything" and saved to `foo_replaced.js`
```
-### Positionals
+More examples [below](#mag_right-examples-and-recipes---cli).
+
+### Arguments
-| Option | Type | Description |
+| Argument | Type | Description |
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| \ | string | First parameter to [RegExp constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) |
| \ | string | String or path to replacement function file (see ‑‑replace‑fn switch for details) |
-### Options
+### Flags
> Note: Every boolean option can be negated with use of `--no-` prefix, e.g. `--stdout` or `--no-stdout` turn stdout output on or off, respectively.
@@ -73,7 +89,7 @@ frs-replace [options]
| ‑‑o-join-str | string | \n | Used when joining multiple files, passed directly to [javascript join](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#Syntax) |
| ‑c, ‑‑content | string | _-_ | Content to be replaced (takes precedence over stream & file input) |
| ‑s, ‑‑strategy | "join" or "flatten" or "preserve-structure" | "join" | Output file generation strategy. _"join"_ - joins all input files and outputs them as a single file using path passed as: _"output"_. _"preserve-structure"_ - saves all files to the _"output"_ directory keeping relative directory structure._"flatten"_ - same as _"preserve-structure"_ but flattens the directory structure |
-| ‑f, ‑‑flags | combination of _gim_ flags | g | [RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) flags |
+| ‑f, ‑‑flags | string, combination of _gim_ flags | g | [RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) flags |
| ‑‑stdout | boolean | _true_ if piped input present, _false_ otherwise | Force sending output on stdout |
| ‑r, ‑‑replace‑fn | boolean | false | Treat replacement argument as path to file containing replacement function |
| ‑h, ‑‑help | boolean | _-_ | Show help |
@@ -81,43 +97,43 @@ frs-replace [options]
## :mag_right: Examples and recipes - CLI
-### 1. Replace all `a` occurrences with `b` from the `foo.js` file and return the result (using CLI)
+##### 1. Replace all `a` occurrences with `b` from the `foo.js` file and return the result (using CLI)
```bash
frs-replace a b -i foo.js --stdout
```
-### 2. Replace all `a` occurrences with `b` from `foo.js` and save the result to the `foo_replaced.js` (using CLI)
+##### 2. Replace all `a` occurrences with `b` from `foo.js` and save the result to the `foo_replaced.js` (using CLI)
```bash
frs-replace a b -i foo.js -o foo_replaced.js
```
-### 3. Replace all `a` occurrences with `b` from an array of files and save the result to the `foo_replaced.js` using default `\n` as a result-joining string (using CLI)
+##### 3. Replace all `a` occurrences with `b` from an array of files and save the result to the `foo_replaced.js` using default `\n` as a result-joining string (using CLI)
```bash
frs-replace a b -i foo.js -i foo2.js -o foo_replaced.js
```
-### 4. Replace all `a` occurrences with `b` from all `.js` files in the `foo` directory and save the result to the `foo_replaced.js` using `\n/////\n` as a result-joining string (using CLI)
+##### 4. Replace all `a` occurrences with `b` from all `.js` files in the `foo` directory and save the result to the `foo_replaced.js` using `\n/////\n` as a result-joining string (using CLI)
```bash
frs-replace a b -i foo/*.js -o foo_replaced.js --o-join-str "\n/////\n"
```
-### 5. Replace all `a` occurrences with `b` in a content string `abcd` and save the result to the `foo_replaced.js` (using CLI)
+##### 5. Replace all `a` occurrences with `b` in a content string `abcd` and save the result to the `foo_replaced.js` (using CLI)
```bash
frs-replace a b --content abcd -o foo_replaced.js
```
-### 6. Replace all `a` occurrences with `b` from a piped stream and save it to the output file (using CLI)
+##### 6. Replace all `a` occurrences with `b` from a piped stream and save it to the output file (using CLI)
```bash
| frs-replace a b >
```
-### 7. Replace all `a` occurrences with `b` from a piped stream and pass it through the `stdout` stream to the `` (using CLI)
+##### 7. Replace all `a` occurrences with `b` from a piped stream and pass it through the `stdout` stream to the `` (using CLI)
```bash
| frs-replace a b |
@@ -133,7 +149,7 @@ import { sync, async } from '@frsource/frs-replace';
sync({
/* options */
});
-async({
+await async({
/* options */
});
```
@@ -159,7 +175,7 @@ Where `/* options */` is an object containing:
> Note: While all of examples are using synchronous API method in all cases your can use `async` as well.
-### 1. Replace all `a` occurrences with `b` from the `foo.js` file and return the result
+##### 1. Replace all `a` occurrences with `b` from the `foo.js` file and return the result
```javascript
import { sync } from '@frsource/frs-replace';
@@ -172,7 +188,7 @@ const result = sync({
});
```
-### 2. Replace all `a` occurrences with `b` from `foo.js` and save the result to the `foo_replaced.js`
+##### 2. Replace all `a` occurrences with `b` from `foo.js` and save the result to the `foo_replaced.js`
```javascript
import { sync } from '@frsource/frs-replace';
@@ -184,7 +200,7 @@ const result = sync({
});
```
-### 3. Replace all `a` occurrences with `b` from an array of files and save the result to the `foo_replaced.js` using default `\n` as a result-joining string
+##### 3. Replace all `a` occurrences with `b` from an array of files and save the result to the `foo_replaced.js` using default `\n` as a result-joining string
```javascript
import { sync } from '@frsource/frs-replace';
@@ -196,7 +212,7 @@ const result = sync({
});
```
-### 4. Replace all `a` occurrences with `b` from all `.js` files in the `foo` directory and save the result to the `foo_replaced.js` using `\n/////\n` as a result-joining string
+##### 4. Replace all `a` occurrences with `b` from all `.js` files in the `foo` directory and save the result to the `foo_replaced.js` using `\n/////\n` as a result-joining string
```javascript
import { sync } from '@frsource/frs-replace';
@@ -209,7 +225,7 @@ const result = sync({
});
```
-### 5. Replace all `a` occurrences with `b` in a content string `abcd` and save the result to the `foo_replaced.js`
+##### 5. Replace all `a` occurrences with `b` in a content string `abcd` and save the result to the `foo_replaced.js`
```javascript
import { sync } from '@frsource/frs-replace';