diff --git a/jib-cli/README.md b/jib-cli/README.md
index a6db53d61f..214f234dfd 100644
--- a/jib-cli/README.md
+++ b/jib-cli/README.md
@@ -1,24 +1,34 @@
# Jib CLI
-
+
-`jib` is a command-line utility for building containers images from file system content.
-It serves as a demonstration of [Jib Core](https://github.com/GoogleContainerTools/jib/tree/master/jib-core),
-a Java library for building containers without Docker.
+`jib` is a general-purpose command-line utility for building Docker or [OCI](https://github.com/opencontainers/image-spec) container images from file system content as well as JAR files. Jib CLI builds containers [fast and reproducibly without Docker](https://github.com/GoogleContainerTools/jib#goals) like [other Jib tools](https://github.com/GoogleContainerTools/jib#what-is-jib).
-This CLI tool is _experimental_ and its options and structure
-are almost certain to change.
+```sh
+# docker not required
+$ docker
+-bash: docker: command not found
+# build and upload an image
+$ jib build --target=my-registry.example.com/built-by-jib
+```
+
+Additionally, Jib CLI can directly build an optimized image for JAR files (including Spring Boot fat JAR).
+```sh
+$ jib jar --target=my-registry.example.com/jar-app myapp.jar
+```
+
+The CLI tool is powered by [Jib Core](https://github.com/GoogleContainerTools/jib/tree/master/jib-core), a Java library for building containers without Docker.
## Table of Contents
* [Get the Jib CLI](#get-the-jib-cli)
- * [Download a java application](#download-a-java-application)
- * [Build yourself from source](#build-yourself-from-source)
+ * [Download a Java Application](#download-a-java-application)
+ * [Build Yourself from Source (for Advanced Users)](#build-yourself-from-source-for-advanced-users)
* [Supported Commands](#supported-commands)
-* [Build](#build)
+* [Build Command](#build-command)
* [Quickstart](#quickstart)
* [Fully Annotated `jib.yaml`](#fully-annotated-jibyaml)
* [Options](#options)
-* [Jar](#jar)
+* [Jar Command](#jar-command)
* [Options](#options)
* [Common Jib CLI Options](#common-cli-options)
* [Auth/Security](#authsecurity)
@@ -27,13 +37,15 @@ are almost certain to change.
## Get the Jib CLI
-### Download a java application
+Most users should download a ZIP archive (Java application). We are working on releasing a native executable binary.
+
+### Download a Java Application
A JRE is required to run this Jib CLI distribution.
Find the [latest jib-cli 0.2.0 release](https://github.com/GoogleContainerTools/jib/releases/tag/v0.2.0-cli) on the [Releases page](https://github.com/GoogleContainerTools/jib/releases), download `jib-jre-.zip`, and unzip it. The zip file contains the `jib` (`jib.bat` for Windows) script at `jib/bin/`. Optionally, add the binary directory to your `$PATH` so that you can call `jib` from anywhere.
-### Build yourself from source
+### Build Yourself from Source (for Advanced Users)
Use the `application` plugin's `installDist` task to create a runnable installation in
`build/install/jib`. A zip and tar file are also created in `build/distributions`.
@@ -42,17 +54,15 @@ Use the `application` plugin's `installDist` task to create a runnable installat
$ ./gradlew jib-cli:installDist
# run
$ ./jib-cli/build/install/jib/bin/jib
-```
-
-
+```
## Supported Commands
-The Jib CLI currently supports two commands:
- 1. `build` - To build a container with the help of a build file.
- 2. `jar` - To containerize a jar.
+The Jib CLI supports two commands:
+ 1. `build` - containerizes using a [build file](#fully-annotated-jibyaml).
+ 2. `jar` - containerizes JAR files.
-## Build
+## Build Command
This command follows the following pattern:
```
jib build --target [options]
@@ -181,7 +191,7 @@ layers:
- dest: "/images"
```
-#### Layers behavior
+#### Layers Behavior
- Copy directives are bound by the following rules
`src`: filetype determined by type on local disk
- if `src` is directory, `dest` is always considered a directory, directory and contents will be copied over and renamed to `dest`
@@ -216,12 +226,12 @@ layers:
- "**/exclude-dir/**
```
-#### Base image parameter inheritance
+#### Base Image Parameter Inheritance
Some values defined in the base image may be preserved and propogated into the new container.
Parameters will append to base image value:
- - `volumes`
- - `exposedPorts`
+- `volumes`
+- `exposedPorts`
Parameters that will append any new keys, and overwrite existing keys:
- `labels`
@@ -235,7 +245,7 @@ Parameters that will be overwritten:
### Options
-Here is the list of optional flags for the `build` command:
+Optional flags for the `build` command:
Option | Description
--- | ---
@@ -244,14 +254,14 @@ Option | Description
`-p, --parameter` | Templating parameter to inject into build file, replace ${} with (repeatable)
-## Jar Command: Containerizing a JAR app
+## Jar Command
This command follows the following pattern:
```
jib jar --target path/to/myapp.jar [options]
```
### Options
-Here is a list of optional flags for the `jar` command:
+Optional flags for the `jar` command:
Option | Description
--- | ---
@@ -280,7 +290,7 @@ The options can either be specified in the command line or defined in a configur
--send-credentials-over-http Allow jib to send credentials over http (very insecure)
```
-#### Credentials
+### Credentials
Credentials can be specified using credential helpers or username + password. The following options are available:
```
@@ -313,7 +323,7 @@ Mixed Mode
1. `--to-credential-helper`, `--from-username`, `--from-password`
2. `--from-credential-helper`, `--to-username`, `--to-password`
-#### Info Params
+### Info Params
```
--help print usage and exit
--console set console output type, candidates: auto, rich, plain, default: auto
@@ -321,7 +331,7 @@ Mixed Mode
-v, --version Jib CLI version information
```
-#### Debugging Params
+### Debugging Params
```
--stacktrace print stacktrace on error (for debugging issues in the jib-cli)
--http-trace enable http tracing at level=config, output=console