diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..55128f05 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +docs/zed.md linguist-generated=true \ No newline at end of file diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 92ef35eb..99b17dad 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -7,9 +7,7 @@ on: # yamllint disable-line rule:truthy env: DOCS_REPO: "authzed/docs" - DOCS_BRANCH: "main" - GENERATED_DOCS_FILE: "docs/zed.md" - TARGET_DOCS_FILE: "pages/zed/zed.md" + TARGET_DOCS_FILE: "pages/spicedb/getting-started/installing-zed.mdx" CHANGES_DETECTED: false permissions: @@ -28,7 +26,7 @@ jobs: - uses: "authzed/actions/setup-mage@main" - name: "Generate Documentation" - run: "mage gen:docs" + run: "mage gen:docsForPublish" - name: "Checkout docs repository" uses: "actions/checkout@v4" @@ -41,7 +39,7 @@ jobs: - name: "Sync documentation changes" run: | mkdir -p docs-repo/$(dirname $TARGET_DOCS_FILE) - cp -v $GENERATED_DOCS_FILE docs-repo/$TARGET_DOCS_FILE + cp -v merged.md docs-repo/$TARGET_DOCS_FILE - name: "Create commit & pull request" uses: "peter-evans/create-pull-request@v7" with: diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index 470a83c9..2936654e 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/lint.yaml @@ -29,6 +29,8 @@ jobs: - uses: "actions/checkout@v4" - uses: "authzed/actions/yaml-lint@main" - uses: "authzed/actions/markdown-lint@main" + with: + args: "--ignore docs/zed.md" # auto-generated codeql: name: "Analyze with CodeQL" diff --git a/.gitignore b/.gitignore index 48728aac..a7fe944c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ dist/ temp/ -docs/ +docs/merged.md # Local-only files go.work diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..6d0ce1d5 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,88 @@ +# zed + +## Getting Started + +### Installing the binary + +Binary releases are available for Linux, macOS, and Windows on AMD64 and ARM64 architectures. + +[Homebrew] users for both macOS and Linux can install the latest binary releases of zed using the official tap: + +```sh +brew install authzed/tap/zed +``` + +[Debian-based Linux] users can install zed packages by adding a new APT source: + +First, download the public signing key for the repository: + +```sh +# In releases older than Debian 12 and Ubuntu 22.04, the folder `/etc/apt/keyrings` does not exist by default, and it should be created before the curl command. +# sudo mkdir -p -m 755 /etc/apt/keyrings + +curl -sS https://pkg.authzed.com/apt/gpg.key | sudo gpg --dearmor --yes -o /etc/apt/keyrings/authzed.gpg +``` + +Then add the list file for the repository: + +```sh +echo "deb [signed-by=/etc/apt/keyrings/authzed.gpg] https://pkg.authzed.com/apt/ * *" | sudo tee /etc/apt/sources.list.d/authzed.list +sudo chmod 644 /etc/apt/sources.list.d/authzed.list # helps tools such as command-not-found to work correctly + +``` + +Alternatively, if you want to use the new `deb822`-style `authzed.sources` format, put the following in `/etc/apt/sources.list.d/authzed.sources`: + +```yaml +Types: deb +URIs: https://pkg.authzed.com/apt/ +Suites: * +Components: * +Signed-By: /etc/apt/keyrings/authzed.gpg +``` + +Once you've defined the sources and updated your apt cache, it can be installed just like any other package: + +```sh +sudo apt update +sudo apt install -y zed +``` + +[RPM-based Linux] users can install zed packages by adding a new YUM repository: + +```sh +sudo cat << EOF >> /etc/yum.repos.d/Authzed-Fury.repo +[authzed-fury] +name=AuthZed Fury Repository +baseurl=https://yum.fury.io/authzed/ +enabled=1 +gpgcheck=0 +EOF +sudo dnf install -y zed +``` + +[homebrew]: https://docs.authzed.com/spicedb/installing#brew +[Debian-based Linux]: https://en.wikipedia.org/wiki/List_of_Linux_distributions#Debian-based +[RPM-based Linux]: https://en.wikipedia.org/wiki/List_of_Linux_distributions#RPM-based + +### Other methods + +#### Docker + +Container images are available for AMD64 and ARM64 architectures on the following registries: + +- [authzed/zed](https://hub.docker.com/r/authzed/zed) +- [ghcr.io/authzed/zed](https://github.com/authzed/zed/pkgs/container/zed) +- [quay.io/authzed/zed](https://quay.io/authzed/zed) + +You can pull down the latest stable release: + +```sh +docker pull authzed/zed +``` + +Afterward, you can run it with `docker run`: + +```sh +docker run --rm authzed/zed version +``` diff --git a/docs/zed.md b/docs/zed.md new file mode 100644 index 00000000..3f29c67c --- /dev/null +++ b/docs/zed.md @@ -0,0 +1,1436 @@ +## Reference: `zed` + +A command-line client for managing SpiceDB clusters. + +### Examples + +``` + +zed context list +zed context set dev localhost:80 testpresharedkey --insecure +zed context set prod grpc.authzed.com:443 tc_zed_my_laptop_deadbeefdeadbeefdeadbeefdeadbeef +zed context use dev +zed permission check --explain document:firstdoc writer user:emilia + +``` + +### Options + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed backup](#zed-backup) - Create, restore, and inspect permissions system backups +* [zed context](#zed-context) - Manage configurations for connecting to SpiceDB deployments +* [zed import](#zed-import) - Imports schema and relationships from a file or url +* [zed permission](#zed-permission) - Query the permissions in a permissions system +* [zed preview](#zed-preview) - Experimental commands that have been made available for preview +* [zed relationship](#zed-relationship) - Query and mutate the relationships in a permissions system +* [zed schema](#zed-schema) - Manage schema for a permissions system +* [zed use](#zed-use) - Alias for `zed context use` +* [zed validate](#zed-validate) - Validates the given validation file (.yaml, .zaml) or schema file (.zed) +* [zed version](#zed-version) - Display zed and SpiceDB version information + + +## Reference: `zed backup` + +Create, restore, and inspect permissions system backups + +``` +zed backup [flags] +``` + +### Options + +``` + --page-limit uint32 defines the number of relationships to be read by requested page during backup + --prefix-filter string include only schema and relationships with a given prefix + --rewrite-legacy potentially modify the schema to exclude legacy/broken syntax +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed backup create](#zed-backup-create) - Backup a permission system to a file +* [zed backup parse-relationships](#zed-backup-parse-relationships) - Extract the relationships from a backup file +* [zed backup parse-revision](#zed-backup-parse-revision) - Extract the revision from a backup file +* [zed backup parse-schema](#zed-backup-parse-schema) - Extract the schema from a backup file +* [zed backup redact](#zed-backup-redact) - Redact a backup file to remove sensitive information +* [zed backup restore](#zed-backup-restore) - Restore a permission system from a file + + +## Reference: `zed backup create` + +Backup a permission system to a file + +``` +zed backup create [flags] +``` + +### Options + +``` + --page-limit uint32 defines the number of relationships to be read by requested page during backup + --prefix-filter string include only schema and relationships with a given prefix + --rewrite-legacy potentially modify the schema to exclude legacy/broken syntax +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed backup parse-relationships` + +Extract the relationships from a backup file + +``` +zed backup parse-relationships [flags] +``` + +### Options + +``` + --prefix-filter string Include only relationships with a given prefix +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed backup parse-revision` + +Extract the revision from a backup file + +``` +zed backup parse-revision +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed backup parse-schema` + +Extract the schema from a backup file + +``` +zed backup parse-schema [flags] +``` + +### Options + +``` + --prefix-filter string include only schema and relationships with a given prefix + --rewrite-legacy potentially modify the schema to exclude legacy/broken syntax +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed backup redact` + +Redact a backup file to remove sensitive information + +``` +zed backup redact [flags] +``` + +### Options + +``` + --print-redacted-object-ids prints the redacted object IDs + --redact-definitions redact definitions (default true) + --redact-object-ids redact object IDs (default true) + --redact-relations redact relations (default true) +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed backup restore` + +Restore a permission system from a file + +``` +zed backup restore [flags] +``` + +### Options + +``` + --batch-size uint restore relationship write batch size (default 1000) + --batches-per-transaction uint number of batches per transaction (default 10) + --conflict-strategy string strategy used when a conflicting relationship is found. Possible values: fail, skip, touch (default "fail") + --disable-retries retries when an errors is determined to be retryable (e.g. serialization errors) + --prefix-filter string include only schema and relationships with a given prefix + --request-timeout duration timeout for each request performed during restore (default 30s) + --rewrite-legacy potentially modify the schema to exclude legacy/broken syntax +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed context` + +Manage configurations for connecting to SpiceDB deployments + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed context list](#zed-context-list) - Lists all available contexts +* [zed context remove](#zed-context-remove) - Removes a context +* [zed context set](#zed-context-set) - Creates or overwrite a context +* [zed context use](#zed-context-use) - Sets a context as the current context + + +## Reference: `zed context list` + +Lists all available contexts + +``` +zed context list [flags] +``` + +### Options + +``` + --reveal-tokens display secrets in results +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed context remove` + +Removes a context + +``` +zed context remove +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed context set` + +Creates or overwrite a context + +``` +zed context set +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed context use` + +Sets a context as the current context + +``` +zed context use +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed import` + +Imports schema and relationships from a file or url + +``` +zed import [flags] +``` + +### Examples + +``` + + From a gist: + zed import https://gist.github.com/ecordell/8e3b613a677e3c844742cf24421c08b6 + + From a playground link: + zed import https://play.authzed.com/s/iksdFvCtvnkR/schema + + From pastebin: + zed import https://pastebin.com/8qU45rVK + + From a devtools instance: + zed import https://localhost:8443/download + + From a local file (with prefix): + zed import file:///Users/zed/Downloads/authzed-x7izWU8_2Gw3.yaml + + From a local file (no prefix): + zed import authzed-x7izWU8_2Gw3.yaml + + Only schema: + zed import --relationships=false file:///Users/zed/Downloads/authzed-x7izWU8_2Gw3.yaml + + Only relationships: + zed import --schema=false file:///Users/zed/Downloads/authzed-x7izWU8_2Gw3.yaml + + With schema definition prefix: + zed import --schema-definition-prefix=mypermsystem file:///Users/zed/Downloads/authzed-x7izWU8_2Gw3.yaml + +``` + +### Options + +``` + --batch-size int import batch size (default 1000) + --relationships import relationships (default true) + --schema import schema (default true) + --schema-definition-prefix string prefix to add to the schema's definition(s) before importing + --workers int number of concurrent batching workers (default 1) +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed permission` + +Query the permissions in a permissions system + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed permission bulk](#zed-permission-bulk) - Check a permissions in bulk exists for a resource-subject pairs +* [zed permission check](#zed-permission-check) - Check that a permission exists for a subject +* [zed permission expand](#zed-permission-expand) - Expand the structure of a permission +* [zed permission lookup-resources](#zed-permission-lookup-resources) - Enumerates resources of a given type for which the subject has permission +* [zed permission lookup-subjects](#zed-permission-lookup-subjects) - Enumerates the subjects of a given type for which the subject has permission on the resource + + +## Reference: `zed permission bulk` + +Check a permissions in bulk exists for a resource-subject pairs + +``` +zed permission bulk ... [flags] +``` + +### Options + +``` + --consistency-at-exactly string evaluate at the provided zedtoken + --consistency-at-least string evaluate at least as consistent as the provided zedtoken + --consistency-full evaluate at the newest zedtoken in the database + --consistency-min-latency evaluate at the zedtoken preferred by the database + --explain requests debug information from SpiceDB and prints out a trace of the requests + --json output as JSON + --revision string optional revision at which to check + --schema requests debug information from SpiceDB and prints out the schema used +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed permission check` + +Check that a permission exists for a subject + +``` +zed permission check [flags] +``` + +### Options + +``` + --caveat-context string the caveat context to send along with the check, in JSON form + --consistency-at-exactly string evaluate at the provided zedtoken + --consistency-at-least string evaluate at least as consistent as the provided zedtoken + --consistency-full evaluate at the newest zedtoken in the database + --consistency-min-latency evaluate at the zedtoken preferred by the database + --error-on-no-permission if true, zed will return exit code 1 if subject does not have unconditional permission + --explain requests debug information from SpiceDB and prints out a trace of the requests + --json output as JSON + --schema requests debug information from SpiceDB and prints out the schema used +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed permission expand` + +Expand the structure of a permission + +``` +zed permission expand [flags] +``` + +### Options + +``` + --consistency-at-exactly string evaluate at the provided zedtoken + --consistency-at-least string evaluate at least as consistent as the provided zedtoken + --consistency-full evaluate at the newest zedtoken in the database + --consistency-min-latency evaluate at the zedtoken preferred by the database + --json output as JSON + --revision string optional revision at which to check +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed permission lookup-resources` + +Enumerates resources of a given type for which the subject has permission + +``` +zed permission lookup-resources [flags] +``` + +### Options + +``` + --caveat-context string the caveat context to send along with the lookup, in JSON form + --consistency-at-exactly string evaluate at the provided zedtoken + --consistency-at-least string evaluate at least as consistent as the provided zedtoken + --consistency-full evaluate at the newest zedtoken in the database + --consistency-min-latency evaluate at the zedtoken preferred by the database + --cursor string resume pagination from a specific cursor token + --json output as JSON + --page-limit uint32 limit of relations returned per page + --revision string optional revision at which to check + --show-cursor display the cursor token after pagination (default true) +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed permission lookup-subjects` + +Enumerates the subjects of a given type for which the subject has permission on the resource + +``` +zed permission lookup-subjects [flags] +``` + +### Options + +``` + --caveat-context string the caveat context to send along with the lookup, in JSON form + --consistency-at-exactly string evaluate at the provided zedtoken + --consistency-at-least string evaluate at least as consistent as the provided zedtoken + --consistency-full evaluate at the newest zedtoken in the database + --consistency-min-latency evaluate at the zedtoken preferred by the database + --json output as JSON + --revision string optional revision at which to check +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed preview` + +Experimental commands that have been made available for preview + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed preview schema](#zed-preview-schema) - Manage schema for a permissions system + + +## Reference: `zed preview schema` + +Manage schema for a permissions system + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed preview schema compile](#zed-preview-schema-compile) - Compile a schema that uses extended syntax into one that can be written to SpiceDB + + +## Reference: `zed preview schema compile` + +Compile a schema that uses extended syntax into one that can be written to SpiceDB + +``` +zed preview schema compile [flags] +``` + +### Examples + +``` + + Write to stdout: + zed preview schema compile root.zed + Write to an output file: + zed preview schema compile root.zed --out compiled.zed + +``` + +### Options + +``` + --out string output filepath; omitting writes to stdout +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed relationship` + +Query and mutate the relationships in a permissions system + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed relationship bulk-delete](#zed-relationship-bulk-delete) - Deletes relationships matching the provided pattern en masse +* [zed relationship create](#zed-relationship-create) - Create a relationship for a subject +* [zed relationship delete](#zed-relationship-delete) - Deletes a relationship +* [zed relationship read](#zed-relationship-read) - Enumerates relationships matching the provided pattern +* [zed relationship touch](#zed-relationship-touch) - Idempotently updates a relationship for a subject +* [zed relationship watch](#zed-relationship-watch) - Watches the stream of relationship updates from the server + + +## Reference: `zed relationship bulk-delete` + +Deletes relationships matching the provided pattern en masse + +``` +zed relationship bulk-delete [flags] +``` + +### Options + +``` + --force force deletion of all elements in batches defined by + --optional-limit uint32 the max amount of elements to delete. If you want to delete all in batches of size , set --force to true (default 1000) + --subject-filter string optional subject filter +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed relationship create` + +Create a relationship for a subject + +``` +zed relationship create [flags] +``` + +### Options + +``` + -b, --batch-size int batch size when writing streams of relationships from stdin (default 100) + --caveat string the caveat for the relationship, with format: 'caveat_name:{"some":"context"}' + --expiration-time string the expiration time of the relationship in RFC 3339 format + --json output as JSON +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed relationship delete` + +Deletes a relationship + +``` +zed relationship delete [flags] +``` + +### Options + +``` + -b, --batch-size int batch size when deleting streams of relationships from stdin (default 100) + --json output as JSON +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed relationship read` + +Enumerates relationships matching the provided pattern. + +To filter returned relationships using a resource ID prefix, append a '%' to the resource ID: + +zed relationship read some-type:some-prefix-% + + +``` +zed relationship read [flags] +``` + +### Options + +``` + --consistency-at-exactly string evaluate at the provided zedtoken + --consistency-at-least string evaluate at least as consistent as the provided zedtoken + --consistency-full evaluate at the newest zedtoken in the database + --consistency-min-latency evaluate at the zedtoken preferred by the database + --json output as JSON + --page-limit uint32 limit of relations returned per page (default 100) + --subject-filter string optional subject filter +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed relationship touch` + +Idempotently updates a relationship for a subject + +``` +zed relationship touch [flags] +``` + +### Options + +``` + -b, --batch-size int batch size when writing streams of relationships from stdin (default 100) + --caveat string the caveat for the relationship, with format: 'caveat_name:{"some":"context"}' + --expiration-time string the expiration time for the relationship in RFC 3339 format + --json output as JSON +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed relationship watch` + +Watches the stream of relationship updates from the server + +``` +zed relationship watch [object_types, ...] [start_cursor] [flags] +``` + +### Options + +``` + --filter optional_resource_type:optional_resource_id_or_prefix#optional_relation@optional_subject_filter optional filter(s) for the watch stream. Example: optional_resource_type:optional_resource_id_or_prefix#optional_relation@optional_subject_filter + --object_types strings optional object types to watch updates for + --revision string optional revision at which to start watching + --timestamp shows timestamp of incoming update events +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed schema` + +Manage schema for a permissions system + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + +### Children commands + +* [zed schema copy](#zed-schema-copy) - Copy a schema from one context into another +* [zed schema diff](#zed-schema-diff) - Diff two schema files +* [zed schema read](#zed-schema-read) - Read the schema of a permissions system +* [zed schema write](#zed-schema-write) - Write a schema file (.zed or stdin) to the current permissions system + + +## Reference: `zed schema copy` + +Copy a schema from one context into another + +``` +zed schema copy [flags] +``` + +### Options + +``` + --json output as JSON + --schema-definition-prefix string prefix to add to the schema's definition(s) before writing +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed schema diff` + +Diff two schema files + +``` +zed schema diff +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed schema read` + +Read the schema of a permissions system + +``` +zed schema read [flags] +``` + +### Options + +``` + --json output as JSON +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed schema write` + +Write a schema file (.zed or stdin) to the current permissions system + +``` +zed schema write [flags] +``` + +### Options + +``` + --json output as JSON + --schema-definition-prefix string prefix to add to the schema's definition(s) before writing +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed use` + +Alias for `zed context use` + +``` +zed use +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed validate` + +Validates the given validation file (.yaml, .zaml) or schema file (.zed) + +``` +zed validate [flags] +``` + +### Examples + +``` + + From a local file (with prefix): + zed validate file:///Users/zed/Downloads/authzed-x7izWU8_2Gw3.yaml + + From a local file (no prefix): + zed validate authzed-x7izWU8_2Gw3.yaml + + From a gist: + zed validate https://gist.github.com/ecordell/8e3b613a677e3c844742cf24421c08b6 + + From a playground link: + zed validate https://play.authzed.com/s/iksdFvCtvnkR/schema + + From pastebin: + zed validate https://pastebin.com/8qU45rVK + + From a devtools instance: + zed validate https://localhost:8443/download +``` + +### Options + +``` + --force-color force color code output even in non-tty environments + --schema-type string force validation according to specific schema syntax ("", "composable", "standard") +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + +## Reference: `zed version` + +Display zed and SpiceDB version information + +``` +zed version [flags] +``` + +### Options + +``` + --include-deps include dependencies' versions + --include-remote-version whether to display the version of Authzed or SpiceDB for the current context (default true) +``` + +### Options Inherited From Parent Flags + +``` + --certificate-path string path to certificate authority used to verify secure connections + --endpoint string spicedb gRPC API endpoint + --hostname-override string override the hostname used in the connection to the endpoint + --insecure connect over a plaintext connection + --log-format string format of logs ("auto", "console", "json") (default "auto") + --log-level string verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info") + --max-message-size int maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed + --max-retries uint maximum number of sequential retries to attempt when a request fails (default 10) + --no-verify-ca do not attempt to verify the server's certificate chain and host name + --permissions-system string permissions system to query + --proxy string specify a SOCKS5 proxy address + --request-id string optional id to send along with SpiceDB requests for tracing + --skip-version-check if true, no version check is performed against the server + --token string token used to authenticate to SpiceDB +``` + + + diff --git a/magefiles/gen.go b/magefiles/gen.go index d69b8fc2..7edbf0bb 100644 --- a/magefiles/gen.go +++ b/magefiles/gen.go @@ -8,6 +8,7 @@ import ( "github.com/jzelinskie/cobrautil/v2/cobrazerolog" "github.com/magefile/mage/mg" + "github.com/magefile/mage/sh" "github.com/authzed/zed/internal/cmd" ) @@ -32,3 +33,12 @@ func (g Gen) Docs() error { return GenCustomMarkdownTree(rootCmd, targetDir) } + +// DocsForPublish generates a markdown file for publishing in the docs website. +func (g Gen) DocsForPublish() error { + if err := g.Docs(); err != nil { + return err + } + + return sh.RunV("bash", "-c", "cat docs/getting-started.md <(echo -e '\\n') docs/zed.md > docs/merged.md") +} diff --git a/magefiles/util.go b/magefiles/util.go index 4ab19ecb..4ed7935d 100644 --- a/magefiles/util.go +++ b/magefiles/util.go @@ -60,12 +60,13 @@ func genMarkdownTreeCustom(cmd *cobra.Command, f *os.File) error { func collectCommandContent(cmd *cobra.Command, commandContents *[]CommandContent) { buf := new(bytes.Buffer) + name := cmd.CommandPath() - buf.WriteString("## " + name + "\n\n") - buf.WriteString(cmd.Short + "\n\n") - if len(cmd.Long) > 0 { - buf.WriteString("### Synopsis\n\n") + buf.WriteString("## Reference: `" + name + "`\n\n") + if len(cmd.Short) > 0 && len(cmd.Long) == 0 { + buf.WriteString(cmd.Short + "\n\n") + } else if len(cmd.Short) > 0 { buf.WriteString(cmd.Long + "\n\n") } @@ -82,29 +83,21 @@ func collectCommandContent(cmd *cobra.Command, commandContents *[]CommandContent fmt.Println("Error printing options:", err) } - if hasSeeAlso(cmd) { - buf.WriteString("### SEE ALSO\n\n") - if cmd.HasParent() { - parent := cmd.Parent() - pname := parent.CommandPath() - pname = strings.ReplaceAll(strings.ReplaceAll(pname, "_", "-"), " ", "-") - - buf.WriteString(fmt.Sprintf("* [%s](#%s)\t - %s\n", pname, pname, parent.Short)) - } - - children := cmd.Commands() - sort.Sort(byName(children)) + children := cmd.Commands() + sort.Sort(byName(children)) - for _, child := range children { - if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() { - continue - } - cname := name + " " + child.Name() - link := strings.ReplaceAll(strings.ReplaceAll(cname, "_", "-"), " ", "-") - buf.WriteString(fmt.Sprintf("* [%s](#%s)\t - %s\n", cname, link, child.Short)) + if len(children) > 0 { + buf.WriteString("### Children commands\n\n") + } + for _, child := range children { + if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() { + continue } - buf.WriteString("\n\n") + cname := name + " " + child.Name() + link := strings.ReplaceAll(strings.ReplaceAll(cname, "_", "-"), " ", "-") + buf.WriteString(fmt.Sprintf("* [%s](#%s)\t - %s\n", cname, link, child.Short)) } + buf.WriteString("\n\n") *commandContents = append(*commandContents, CommandContent{ Name: name,