dagger CLI spec
Signed-off-by: Solomon Hykes <sh.github.6811@hykes.org>
This commit is contained in:
parent
5dd7dea6af
commit
f7e4279ef8
300
dagger/cli.cue
Normal file
300
dagger/cli.cue
Normal file
@ -0,0 +1,300 @@
|
||||
// This is the source of truth for the DESIRED STATE of the dagger command-line user interface (UI)
|
||||
//
|
||||
// - The CLI implementation is written manually, using this document as a spec. If you spot
|
||||
// a discrepancy between the spec and implementation, please report it or even better,
|
||||
// submit a patch to the implementation.
|
||||
//
|
||||
// - To propose changes to the UI, submit a patch to this spec. Patches to the CLI implementation
|
||||
// which don't match the spec will be rejected.
|
||||
//
|
||||
// - It is OK to propose changes to the CLI spec before an implementation is ready. To speed up
|
||||
// development, we tolerate a lag between the spec and implementation. This may change in the
|
||||
// future once the project is more mature.
|
||||
|
||||
package cli
|
||||
|
||||
import (
|
||||
"text/tabwriter"
|
||||
)
|
||||
|
||||
// Examples:
|
||||
//
|
||||
// cue eval --out text
|
||||
// cue eval --out text -e '#Dagger.command.query.usage'
|
||||
#Dagger.usage
|
||||
|
||||
#Dagger: #Command & {
|
||||
|
||||
name: "dagger"
|
||||
description: "A system for application delivery as code (ADC)"
|
||||
|
||||
doc: """
|
||||
Every dagger operation happens inside a STACK: an isolated sandbox with its own state and execution environment.
|
||||
|
||||
A stack is made of 3 layers:
|
||||
1. Base configuration (see `dagger base`)
|
||||
2. Input values and artifacts (see `dagger input`)
|
||||
3. Output values and artifacts (see `dagger output`)
|
||||
|
||||
If a command does not specify a stack explicitly, dagger tries to auto-select by searching for stacks connected
|
||||
to the current directory, either as a base, input or base:
|
||||
- If no stack matches the search, the command fails
|
||||
- If exactly one stack matches, the command proceeds in that stack
|
||||
- If more than one stack matches, the user is prompted to select one of them
|
||||
"""
|
||||
|
||||
flag: {
|
||||
"--workspace": {
|
||||
alt: "-w"
|
||||
description: "Select a workspace"
|
||||
default: "$HOME/.dagger"
|
||||
}
|
||||
"--stack": {
|
||||
alt: "-s"
|
||||
description: "Select a stack"
|
||||
arg: "NAME"
|
||||
}
|
||||
"--log-format": {
|
||||
arg: "string"
|
||||
description: "Log format (json, pretty). Defaults to json if the terminal is not a tty"
|
||||
}
|
||||
"--log-level": {
|
||||
alt: "-l"
|
||||
arg: "string"
|
||||
description: "Log level"
|
||||
default: "debug"
|
||||
}
|
||||
}
|
||||
|
||||
command: {
|
||||
new: {
|
||||
description: "Create a new stack"
|
||||
flag: {
|
||||
"--name": {
|
||||
alt: "-n"
|
||||
description: "Specify a stack name"
|
||||
default: "name of current directory"
|
||||
}
|
||||
|
||||
"--base-dir": description: "Load base configuration from a local directory"
|
||||
|
||||
"--base-git": description: "Load base configuration from a git repository"
|
||||
|
||||
"--base-package": description: "Load base configuration from a cue package"
|
||||
|
||||
"--base-file": description: "Load base configuration from a cue or json file"
|
||||
|
||||
"--up": {
|
||||
alt: "-u"
|
||||
description: "Bring the stack online"
|
||||
}
|
||||
|
||||
"--setup": {
|
||||
arg: "no|yes|auto"
|
||||
description: "Specify whether to prompt user for initial setup"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
list: description: "List available stacks"
|
||||
|
||||
query: {
|
||||
arg: "[EXPR] [flags]"
|
||||
description: "Query the contents of a stack"
|
||||
doc:
|
||||
"""
|
||||
EXPR may be any valid CUE expression. The expression is evaluated against the stack contents. The stack is not changed.
|
||||
Examples:
|
||||
|
||||
# Print all contents of the input and base layers (omit output)
|
||||
$ dagger query -l input,base
|
||||
|
||||
# Print complete contents for a particular component
|
||||
$ dagger query www.build
|
||||
|
||||
# Print the URL of a deployed service
|
||||
$ dagger query api.url
|
||||
|
||||
# Export environment variables from a deployment
|
||||
$ dagger query -f json api.environment
|
||||
|
||||
"""
|
||||
|
||||
flag: {
|
||||
|
||||
// FIXME: confusing flag choice?
|
||||
// Use --revision or --change or --change-id instead?
|
||||
"--version": {
|
||||
alt: "-v"
|
||||
description: "Query a specific version of the stack"
|
||||
default: "latest"
|
||||
}
|
||||
|
||||
"--format": {
|
||||
alt: "-f"
|
||||
description: "Output format"
|
||||
arg: "json|yaml|cue|text|env"
|
||||
}
|
||||
|
||||
"--layer": {
|
||||
alt: "-l"
|
||||
description: """
|
||||
Comma-separated list of layers to query (any of "input", "base", "output")
|
||||
"""
|
||||
default: "all"
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
up: {
|
||||
description: "Bring a stack online using latest base and inputs"
|
||||
flag: "--no-cache": description: "Disable all run cache"
|
||||
}
|
||||
|
||||
down: {
|
||||
description: "Take a stack offline (WARNING: may destroy infrastructure)"
|
||||
flag: "--no-cache": description: "Disable all run cache"
|
||||
}
|
||||
|
||||
history: description: "List past changes to a stack"
|
||||
|
||||
destroy: {
|
||||
description: "Destroy a stack"
|
||||
|
||||
flag: "--force": {
|
||||
alt: "-f"
|
||||
description: "Destroy environment state even if cleanup pipelines fail to complete (EXPERTS ONLY)"
|
||||
}
|
||||
}
|
||||
|
||||
base: {
|
||||
description: "Manage a stack's base configuration"
|
||||
|
||||
command: {
|
||||
package: {
|
||||
description: "Load base configuration from a cue package"
|
||||
arg: "PKG"
|
||||
doc:
|
||||
"""
|
||||
Examples:
|
||||
dagger base package dagger.io/templates/jamstack
|
||||
"""
|
||||
}
|
||||
|
||||
dir: {
|
||||
description: "Load base configuration from a local directory"
|
||||
arg: "PATH"
|
||||
doc:
|
||||
"""
|
||||
Examples:
|
||||
dagger base dir ./infra/prod
|
||||
"""
|
||||
}
|
||||
|
||||
git: {
|
||||
description: "Load base configuration from a git repository"
|
||||
arg: "REMOTE REF [SUBDIR]"
|
||||
doc:
|
||||
"""
|
||||
Examples:
|
||||
dagger base git https://github.com/dagger/dagger main examples/simple
|
||||
"""
|
||||
}
|
||||
|
||||
file: {
|
||||
description: "Load base configuration from a cue file"
|
||||
arg: "PATH|-"
|
||||
doc:
|
||||
"""
|
||||
Examples:
|
||||
dagger base file ./base.cue
|
||||
echo 'message: "hello, \(name)!", name: string | *"world"' | dagger base file -
|
||||
"""
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
input: {
|
||||
description: "Manage a stack's inputs"
|
||||
|
||||
command: {
|
||||
// FIXME: details of individual input commands
|
||||
dir: {description: "Add a local directory as input artifact"}
|
||||
git: description: "Add a git repository as input artifact"
|
||||
container: description: "Add a container image as input artifact"
|
||||
value: description: "Add an input value"
|
||||
secret: description: "Add an encrypted input secret"
|
||||
}
|
||||
}
|
||||
|
||||
output: {
|
||||
description: "Manage a stack's outputs"
|
||||
// FIXME: bind output values or artifacts
|
||||
// to local dir or file
|
||||
// BONUS: bind a stack output to another stack's input?
|
||||
}
|
||||
|
||||
login: description: "Login to Dagger Cloud"
|
||||
|
||||
logout: description: "Logout from Dagger Cloud"
|
||||
}
|
||||
}
|
||||
|
||||
#Command: {
|
||||
// Command name
|
||||
name: string
|
||||
|
||||
description: string
|
||||
doc: string | *""
|
||||
|
||||
// Flags
|
||||
flag: [fl=string]: #Flag & {name: fl}
|
||||
flag: "--help": {
|
||||
alt: "-h"
|
||||
description: "help for \(name)"
|
||||
}
|
||||
|
||||
// Sub-commands
|
||||
command: [cmd=string]: #Command & {
|
||||
name: cmd
|
||||
}
|
||||
|
||||
arg: string | *"[command]"
|
||||
|
||||
usage: {
|
||||
"""
|
||||
\(description)
|
||||
\(doc)
|
||||
|
||||
Usage:
|
||||
\(name) \(arg)
|
||||
|
||||
Available commands:
|
||||
\(tabwriter.Write(#commands))
|
||||
|
||||
Flags:
|
||||
\(tabwriter.Write(#flags))
|
||||
"""
|
||||
|
||||
#commands: [ for name, cmd in command {
|
||||
"""
|
||||
\(name)\t\(cmd.description)
|
||||
"""
|
||||
}]
|
||||
#flags: [ for name, fl in flag {
|
||||
"""
|
||||
\(name), \(fl.alt)\t\(fl.description)
|
||||
"""
|
||||
}]
|
||||
}
|
||||
}
|
||||
|
||||
#Flag: {
|
||||
name: string
|
||||
alt: string | *""
|
||||
description: string
|
||||
default?: string
|
||||
arg?: string
|
||||
example?: string
|
||||
}
|
Reference in New Issue
Block a user