Fix apache#1449: document modeline and CLI

docs/modules/ROOT/nav-end.adoc

@@ -1,4 +1,2 @@
-* xref:tutorials/tutorials.adoc[Tutorials]
-** xref:tutorials/tekton/tekton.adoc[Tekton Pipelines]
 * xref:uninstalling.adoc[Uninstalling]
 * xref:developers.adoc[Contributing to Camel K]

docs/modules/ROOT/nav.adoc

@@ -9,6 +9,10 @@
 *** xref:installation/registry/gcr.adoc[Gcr.io]
 * xref:running/running.adoc[Running]
 ** xref:running/dev-mode.adoc[Dev Mode]
+* xref:tutorials/tutorials.adoc[Tutorials]
+** xref:tutorials/tekton/tekton.adoc[Tekton Pipelines]
+* xref:cli/cli.adoc[CLI]
+** xref:cli/modeline.adoc[Modeline]
 * xref:configuration/configuration.adoc[Configuration]
 ** xref:configuration/components.adoc[Components]
 ** xref:configuration/logging.adoc[Logging]

docs/modules/ROOT/pages/cli/cli.adoc

@@ -0,0 +1,54 @@
+= Camel K CLI (kamel)
+
+The Camel K command line interface (kamel) is the main entry point for running integrations on a Kubernetes cluster.
+
+Releases of the Camel K CLI are available on:
+
+- Apache Mirrors (official): https://downloads.apache.org/camel/camel-k/
+- Github Releases: https://github.com/apache/camel-k/releases
+- Homebrew (Mac and Linux): https://formulae.brew.sh/formula/kamel
+
+== Available Commands
+
+Some of the most used commands are:
+
+.Useful Commands
+|===
+|Name |Description |Example
+
+|help
+|Obtain the full list of available commands
+|`kamel help`
+
+|init
+|Initialize empty Camel K files
+|`kamel init Routes.java`
+
+|run
+|Run an integration on Kubernetes
+|`kamel run Routes.java`
+
+|get
+|Get integrations deployed on Kubernetes
+|`kamel get`
+
+|describe
+|Get detailed information on a resource
+|`kamel describe integration routes`
+
+|log
+|Print the logs of a running integration
+|`kamel log routes`
+
+|delete
+|Delete integrations deployed on Kubernetes
+|`kamel delete routes`
+
+|===
+
+The list above is not the full list of available commands. You can run `kamel help` to obtain the full list.
+
+== Modeline
+
+Some command options in the CLI can be also specified as modeline in the source file, take a look at the xref:cli/modeline.adoc[Modeline section]
+for more information.

docs/modules/ROOT/pages/cli/modeline.adoc

@@ -0,0 +1,98 @@
+= Camel K Modeline
+
+Integration files can contain modeline hooks that allow to customize the way integrations are executed via command line.
+
+For example, take the following integration file:
+
+.Hello.java
+----
+// camel-k: dependency=mvn:org.my:application:1.0 // <1>
+
+import org.apache.camel.builder.RouteBuilder;
+
+public class Hello extends RouteBuilder {
+  @Override
+  public void configure() throws Exception {
+
+      from("timer:java?period=1000")
+        .bean(org.my.BusinessLogic) // <2>
+        .log("${body}");
+
+  }
+}
+----
+<1> Modeline import of Maven library
+<2> Usage of a business logic class from the external library
+
+When the integration code above is executed using the `kamel run` CLI command, the modeline options declared in the file are appended to
+the list of arguments that are passed to the command.
+
+The `kamel` CLI will alert you, printing the full command in the shell:
+
+----
+$ kamel run Hello.java
+Modeline options have been loaded from source files
+Full command: kamel run Hello.java --dependency mvn:org.my:application:1.0
+...
+----
+
+Multiple options, even of the same type, can be specified for an integration. For example
+the following modeline options make sure that the integration runs on the Quarkus runtime and enable the 3scale exposure.
+
+.QuarkusRest.java
+----
+// camel-k: trait=quarkus.enabled=true trait=3scale.enabled=true // <1>
+
+import org.apache.camel.builder.RouteBuilder;
+
+public class QuarkusRest extends RouteBuilder {
+  @Override
+  public void configure() throws Exception {
+
+      rest().get("/")
+        .route()
+        .setBody().constant("Hello");
+
+  }
+}
+----
+<1> Enable both the Quarkus and 3scale traits, to run the integration on Quarkus and expose the routes via 3scale
+
+All options that are available for the `kamel run` command can be specified as modeline options.
+The following is a partial list of useful options:
+
+.Useful Modeline Options
+|===
+|Option | Description
+
+|dependency
+|An external library that should be included. E.g. for Maven dependencies "dependency=mvn:org.my/app:1.0"
+
+|env
+|Set an environment variable in the integration container. E.g "env=MY_VAR=my-value"
+
+|label
+|Add a label to the integration. E.g. "label=my.company=hello"
+
+|name
+|The integration name
+
+|open-api
+|Add an OpenAPI v2 spec (file path)
+
+|profile
+|Trait profile used for deployment
+
+|property
+|Add a camel property
+
+|property-file
+|Bind a property file to the integration. E.g. "property-file=integration.properties"
+
+|resource
+|Add a resource
+
+|trait
+|Configure a trait. E.g. "trait=service.enabled=false"
+
+|===

pkg/cmd/run.go

@@ -72,7 +72,7 @@ func newCmdRun(rootCmdOptions *RootCmdOptions) (*cobra.Command, *runCmdOptions)
 	}
 
 	cmd.Flags().String("name", "", "The integration name")
-	cmd.Flags().StringArrayP("dependency", "d", nil, "The integration dependency")
+	cmd.Flags().StringArrayP("dependency", "d", nil, "An external library that should be included. E.g. for Maven dependencies \"mvn:org.my/app:1.0\"")
 	cmd.Flags().BoolP("wait", "w", false, "Waits for the integration to be running")
 	cmd.Flags().StringP("kit", "k", "", "The kit used to run the integration")
 	cmd.Flags().StringArrayP("property", "p", nil, "Add a camel property")