doc/cmd: refer people to cue help for now
Until such time as we solve #9, maintaining a cmd reference by hand is
bound to go out of sync. Give, per #9, we do plan to generate such a
combined reference one day, leave this file in place with a simple
"redirect" asking people to refer to cue help instead.
Change-Id: Ia232437996c27af5a0ed2ad459bfdaeb50d4c27e
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/9301
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
diff --git a/doc/cmd/cue.md b/doc/cmd/cue.md
index d09c471..6c39bf3 100644
--- a/doc/cmd/cue.md
+++ b/doc/cmd/cue.md
@@ -1,487 +1,9 @@
# `cue` command reference
-This documentation is a formatted from of the builtin documentation of the
-cue help command.
+`cue help` gives information about the various `cue` commands available, as well
+as additional help topics. For example `cue help import` gives information about
+how to convert other formats like JSON and YAML to CUE, and `cue help filetypes`
+describes the `cue` command's support for various file types.
-## General usage
-
-```
-cue [command]
-```
-
-The commands are:
-
-```
- cmd run a user-defined shell command
- eval evaluate a configuration file
- export outputs an evaluated configuration in a standard format
- extract
- fmt formats Cue configuration files.
- help Help about any command
- import convert other data formats to CUE files
- list list packages or modules
- serve starts a builtin or user-defined service
-
-Flags:
- --config string config file (default is $HOME/.cue)
- --debug give detailed error info
- -h, --help help for cue
- --pkg string CUE package to evaluate
- --root load a Cue package from its root
-```
-
-## Start a bug report
-
-TODO
-
-## Evaluate a CUE file
-
-```
-Flags:
- --pkg string Cue package to evaluate
-```
-
-## Formatting CUE files
-
-`fmt` formats the given files or the files for the given packages in place.
-
-Usage:
-```
- cue fmt [-s] [packages] [flags]
-```
-Flags:
-```
- --config string config file (default is $HOME/.cue)
- --debug give detailed error info
- -n, --dryrun only run simulation
- -p, --package string Cue package to evaluate
- -s, --simplify simplify output
-```
-
-## Exporting results
-
-`export` evaluates the configuration found in the current directory
-and prints the emit value to stdout.
-
-Examples:
-Evaluated and emit
-
-```
- # a single file
- cue export config.cue
-
- # multiple files: these are combined at the top-level.
- # Order doesn't matter.
- cue export file1.cue foo/file2.cue
-
- # all files within the "mypkg" package: this includes all files
- # in the current directory and its ancestor directories that are marked
- # with the same package.
- cue export -p cloud
-
- # the -p flag can be omitted if the directory only contains files for
- # the "mypkg" package.
- cue export
-```
-
-### Emit value
-
-For CUE files, the generated configuration is derived from the top-level single expression, the emit value. For example, the file
-
-```
- // config.cue
- arg1: 1
- arg2: "my string"
-
- {
- a: arg1
- b: arg2
- }
- ```
-yields the following JSON:
-```
- {
- "a": 1,
- "b": "my string"
- }
-```
-In absence of arguments, the current directory is loaded as a package instance.
-A package instance for a directory contains all files in the directory and its
-ancestor directories, up to the module root, belonging to the same package.
-
-If the package is not explicitly defined by the '-p' flag, it must be uniquely
-defined by the files in the current directory.
-
-## Import files in another format
-
-`import` converts other data formats, like JSON and YAML to CUE files.
-The following file formats are currently supported:
-
-```
- Format Extensions
- JSON .json .jsonl .ndjson
- YAML .yaml .yml
-```
-
-Files can either be specified explicitly, or inferred from the specified
-packages.
-In either case, the file extension is replaced with `.cue`.
-It will fail if the file already exists by default.
-The -f flag overrides this.
-
-Examples:
-
-```
- # Convert individual files:
- $ cue import foo.json bar.json # create foo.yaml and bar.yaml
-
- # Convert all json files in the indicated directories:
- $ cue import ./... -type=json
-```
-
-
-### The `--path` flag
-
-By default the parsed files are included as emit values.
-This default can be overridden by specifying a path, which has two forms:
-
-```
- -p ident*
-```
-
- and
-```
- -p ident "->" expr*
-```
-
-The first form specifies a fixed path.
-The empty path indicates including the value at the root.
-The second form allows expressing the path in terms of the imported value.
-An unbound identifier in the second form denotes a fixed name.
-Packages may be included with the -imports flag.
-Imports for top-level core packages are elided.
-
-
-### Handling multiple documents or streams
-
-To handle Multi-document files, such as concatenated JSON objects or YAML files
-with document separators (---) the user must specify either the -path, -list, or
--files flag.
-The -path flag assign each element to a path (identical paths are
-treated as usual); -list concatenates the entries, and -files causes each entry
-to be written to a different file.
-The -files flag may only be used if files are explicitly imported.
-The -list flag may be used in combination with the -path
-flag, concatenating each entry to the mapped location.
-
-Examples:
-
-```
- $ cat <<EOF > foo.yaml
- kind: Service
- name: booster
- EOF
-
- # include the parsed file as an emit value:
- $ cue import foo.yaml
- $ cat foo.cue
- {
- kind: Service
- name: booster
- }
-
- # include the parsed file at the root of the Cue file:
- $ cue import -f -p "" foo.yaml
- $ cat foo.cue
- kind: Service
- name: booster
-
- # include the import config at the mystuff path
- $ cue import -f -p mystuff foo.yaml
- $ cat foo.cue
- myStuff: {
- kind: Service
- name: booster
- }
-
- # append another object to the input file
- $ cat <<EOF >> foo.yaml
- ---
- kind: Deployment
- name: booster
- replicas: 1
- EOF
-
- # base the path values on th input
- $ cue import -f -p "x -> strings.ToLower(x.kind) x.name" foo.yaml
- $ cat foo.cue
- service booster: {
- kind: "Service"
- name: "booster"
- }
-
- deployment booster: {
- kind: "Deployment"
- name: "booster
- replicas: 1
- }
-
- # base the path values on th input
- $ cue import -f -list -foo.yaml
- $ cat foo.cue
- [{
- kind: "Service"
- name: "booster"
- }, {
- kind: "Deployment"
- name: "booster
- replicas: 1
- }]
-
- # base the path values on th input
- $ cue import -f -list -p "x->strings.ToLower(x.kind)" foo.yaml
- $ cat foo.cue
- service: [{
- kind: "Service"
- name: "booster"
- }
- deployment: [{
- kind: "Deployment"
- name: "booster
- replicas: 1
- }]
-```
-
-Usage:
-```
- cue import [flags]
-```
-
-Flags:
-```
- --dryrun force overwriting existing files
- --files force overwriting existing files
- -f, --force force overwriting existing files
- -h, --help help for import
- --list concatenate multiple objects into a list
- -n, --name string glob filter for file names
- -o, --out string alternative output or - for stdout
- -p, --path string path to include root
- --type string only apply to files of this type
-```
-
-## Extracting CUE files from source code
-
-TODO: doc
-
-## Running scripts with CUE
-
-`cmd` executes user-defined named commands for each of the listed instances.
-
-Commands define actions on instances.
-For instance, they may define how to upload a configuration to Kubernetes.
-Commands are defined in cue files ending with `_tool.cue` while otherwise using
-the same packaging rules: tool files must have a matching package clause and
-the same rules as for normal files define which will be included in which
-package.
-Tool files have access to the package scope, but none of the fields defined
-in a tool file influence the output of a package.
-Tool files are typically defined at the module root so that they apply
-to all instances.
-
-
-### Tasks
-
-Each command consists of one or more tasks.
-A task may load or write a file, consult a user on the command line,
-or fetch a web page, and so on.
-Each task has inputs and outputs.
-Outputs are typically are typically filled out by the task implementation as
-the task completes.
-
-Inputs of tasks my refer to outputs of other tasks.
-The cue tool does a static analysis of the configuration and only starts tasks
-that are fully specified.
-Upon completion of each task, cue rewrites the instance,
-filling in the completed task, and reevaluates which other tasks can now start,
-and so on until all tasks have completed.
-
-
-### Command definition
-
-Commands are defined at the top-level of the configuration and all follow the
-following pattern:
-
-```
-command <Name>: { // from "cue/tool".Command
- // usage gives a short usage pattern of the command.
- // Example:
- // fmt [-n] [-x] [packages]
- usage: Name | string
-
- // short gives a brief on-line description of the command.
- // Example:
- // reformat package sources
- short: "" | string
-
- // long gives a detailed description of the command, including
- // a description of flags usage and examples.
- long: "" | string
-
- // A task defines a single action to be run as part of this command.
- // Each task can have inputs and outputs, depending on the type
- // task. The outputs are initially unspecified, but are filled out
- // by the tooling
- //
- task <Name>: { // from "cue/tool".Task
- // supported fields depend on type
- }
-
- VarValue = string | bool | int | float | [...string|int|float]
-
- // var declares values that can be set by command line flags or
- // environment variables.
- //
- // Example:
- // // environment to run in
- // var env: "test" | "prod"
- // The tool would print documentation of this flag as:
- // Flags:
- // --env string environment to run in: test(default) or prod
- var <Name>: VarValue
-
- // flag defines a command line flag.
- //
- // Example:
- // var env: "test" | "prod"
- //
- // // augment the flag information for var
- // flag env: {
- // shortFlag: "e"
- // description: "environment to run in"
- // }
- //
- // The tool would print documentation of this flag as:
- // Flags:
- // -e, --env string environment to run in: test(default), staging, or prod
- //
- flag <Name>: { // from "cue/tool".Flag
- // value defines the possible values for this flag.
- // The default is string. Users can define default values by
- // using disjunctions.
- value: env[Name].value | VarValue
-
- // name, if set, allows var to be set with the command-line flag
- // of the given name. null disables the command line flag.
- name: Name | null | string
-
- // short defines an abbreviated version of the flag.
- // Disabled by default.
- short: null | string
- }
-
- // populate flag with the default values for
- flag: { "\(k)": { value: v } | null for k, v in var }
-
- // env defines environment variables. It is populated with values
- // for var.
- //
- // To specify a var without an equivalent environment variable,
- // either specify it as a flag directly or disable the equally
- // named env entry explicitly:
- //
- // var foo: string
- // env foo: null // don't use environment variables for foo
- //
- env <Name>: {
- // name defines the environment variable that sets this flag.
- name: "CUE_VAR_" + strings.Upper(Name) | string | null
-
- // The value retrieved from the environment variable or null
- // if not set.
- value: null | string | bytes
- }
- env: { "\(k)": { value: v } | null for k, v in var }
- }
-```
-
-Available tasks can be found in the package documentation at
-
-```
- cmd/cue/tool/tasks.
- ```
-
-More on tasks can be found in the tasks topic.
-
-Examples
-A simple file using command line execution:
-
-hello.cue:
-```
- package foo
-
- import "cue/tool/tasks/exec"
-
- city: "Amsterdam"
-```
-
-hello_tool.cue:
-```
- package foo
-
- // Say hello!
- command hello: {
- // whom to say hello to
- var who: "World" | string
-
- task print: exec.Run({
- cmd: "echo Hello \(var.who)! Welcome to \(city)."
- })
- }
- ```
-
-Invoking the script on the command line:
-
-```
- $ cue cmd echo
- Hello World! Welcome to Amsterdam.
-
- $ cue cmd echo -who you
- Hello you! Welcome to Amsterdam.
- ```
-An example with tasks depending on each other:
-
-```
-package foo
-
-import "cue/tool/tasks/exec"
-
-city: "Amsterdam"
-
-// Say hello!
-command hello: {
- var file: "out.txt" | string // save transcript to this file
-
- task ask: cli.Ask({
- prompt: "What is your name?"
- response: string
- })
-
- // starts after ask
- task echo: exec.Run({
- cmd: "echo Hello \(task.ask.response)!"
- stdout: string // capture stdout
- })
-
- // starts after echo
- task write: file.Append({
- filename: var.file
- contents: task.echo.stdout
- })
-
- // also starts after echo
- task print: cli.Print({
- contents: task.echo.stdout
- })
-}
-```
+We do plan to provide a web-based version of these various help topics,
+something that is tracked by [#9](https://github.com/cuelang/cue/issues/9).
