kjuulh/dagger
Archived
1
0
Fork 0
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity

dagger CLI spec

Browse Source 
Signed-off-by: Solomon Hykes <sh.github.6811@hykes.org>
This commit is contained in:
Solomon Hykes 2021-02-27 00:14:08 +00:00
parent 5dd7dea6af
commit f7e4279ef8
1 changed files with 300 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

300
dagger/cli.cue Normal file
View 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
}