diff --git a/docs/cli/index.md b/docs/cli/index.md
new file mode 100644
index 0000000..3f213d4
--- /dev/null
+++ b/docs/cli/index.md
@@ -0,0 +1 @@
+# CLI
diff --git a/docs/spec/reference/arg.md b/docs/spec/reference/arg.md
new file mode 100644
index 0000000..f7ffff0
--- /dev/null
+++ b/docs/spec/reference/arg.md
@@ -0,0 +1,20 @@
+# `arg`
+
+```sh
+arg "<file>"                             # positional arg, completed as a filename
+arg "<dir>"                              # positional arg, completed as a directory
+arg "[file]"                             # optional positional arg
+arg "<file>" default="file.txt"          # default value for arg
+arg "<file>" parse="mycli parse-file {}" # parse arg value with external command
+
+arg "[file]" var=true # multiple args can be passed (e.g. mycli file1 file2 file3) (0 or more)
+arg "<file>" var=true # multiple args can be passed (e.g. mycli file1 file2 file3) (1 or more)
+arg "<file>" var=true var_min=3 # at least 3 args must be passed
+arg "<file>" var=true var_max=3 # up to 3 args can be passed
+
+arg "<shell>" {
+  choices "bash" "zsh" "fish" # <shell> must be one of the choices
+}
+
+arg "<file>" long_help="longer help for --help (as oppoosed to -h)"
+```
diff --git a/docs/spec/reference/cmd.md b/docs/spec/reference/cmd.md
new file mode 100644
index 0000000..c95882c
--- /dev/null
+++ b/docs/spec/reference/cmd.md
@@ -0,0 +1,38 @@
+# `cmd`
+
+```sh
+# aliases
+cmd "config" help="Manage the CLI config" {
+  alias "cfg" "cf" "cg"  # aliases for the command
+  alias "conf" hide=true # hide alias from docs and completions
+}
+
+cmd "config" hide=true # hide command from docs and completions
+cmd "config" subcommand_required=true # subcommand is not optional
+
+# these are shown under -h
+cmd "config" before_help="shown before the command"
+cmd "config" help="short description"
+cmd "config" after_help="shown after the command"
+
+# these are shown under --help
+cmd "config" before_long_help="shown before the command"
+cmd "config" long_help="longer description"
+cmd "config" after_long_help="shown after the command"
+
+cmd "list" {
+  example "Basic usage" r#"
+    $ mycli list
+    FRUIT  COLOR
+    apple  red
+    banana yellow
+  "#
+  example "JSON output" r#"
+    $ mycli list --json
+    [
+      {"FRUIT": "apple", "COLOR": "red"},
+      {"FRUIT": "banana", "COLOR": "yellow"}
+    ]
+  "#
+}
+```
diff --git a/docs/spec/reference/complete.md b/docs/spec/reference/complete.md
new file mode 100644
index 0000000..0af6c7e
--- /dev/null
+++ b/docs/spec/reference/complete.md
@@ -0,0 +1,6 @@
+# `complete`
+
+```sh
+# use a custom completion command for args named "PLUGIN"
+complete "<plugin>" run="mycli plugins list" 
+```
diff --git a/docs/spec/reference/flag.md b/docs/spec/reference/flag.md
new file mode 100644
index 0000000..a3845f3
--- /dev/null
+++ b/docs/spec/reference/flag.md
@@ -0,0 +1,34 @@
+# `flag`
+
+```sh
+flag "-u,--user <user>" # one way to define a flag
+flag "--user" { # another way to define the same flag
+  alias "-u"
+  arg "<user>"
+}
+flag "--user" { alias "-u" hide=true } # hide alias from docs and completions
+
+flag "-f,--force" global=true           # global can be set on any subcommand
+flag "--file <file>" default="file.txt" # default value for flag
+flag "-v,--verbose" count=true          # instead of true/false $usage_verbose is # of times
+                                        # flag was used (e.g. -vvv = 3)
+
+flag "--color" negate="--no-color" default=true  # $usage_color=true by default
+                                                 # --no-color will set $usage_color=false
+
+flag "--color" env="MYCLI_COLOR" # flag can be backed by an env var
+flag "--color" config="ui.color" # flag can be backed by a config file
+
+flag "--file <file>"  # args named "<file>" will be completed as files
+flag "--dir <dir>"    # args named "<dir>" will be completed as directories
+
+flag "--file <file>" required_if="--dir"     # if --dir is set, --file must also be set
+flag "--file <file>" required_unless="--dir" # either --file or --dir must be present
+flag "--file <file>" overrides="--stdin"     # if --file is set, previous --stdin will be ignored
+
+flag "--file <file>" long_help="longer help for --help (as oppoosed to -h)"
+
+flag "--shell <shell>" {
+  choices "bash" "zsh" "fish" # <shell> must be one of the choices
+}
+```
diff --git a/docs/spec/reference/index.md b/docs/spec/reference/index.md
new file mode 100644
index 0000000..d1f74e5
--- /dev/null
+++ b/docs/spec/reference/index.md
@@ -0,0 +1,24 @@
+# Top-level metadata
+
+::: warning
+This spec is still a work in progress and is subject to change until 1.0
+:::
+
+```sh
+name "My CLI"        # a friendly name for the CLI
+bin "mycli"          # the name of the binary
+version "1.0.0"      # the version of the CLI
+author "nobody"      # the author of the CLI
+license "MIT"        # SPDX license the CLI is released under
+
+# help for -h
+before_help "before about"
+about "some help"
+after_help "after about"
+
+# help for --help
+before_long_help "before about"
+long_about "longer help"
+after_long_help "after about"
+example "mycli --help"
+```