From a1537b6bd66a5439765f33f8b333b1212136cd80 Mon Sep 17 00:00:00 2001 From: Jahvon Dockery Date: Sun, 6 Oct 2024 19:32:27 -0400 Subject: [PATCH] docs: add workspace and interactive documentation --- docs/README.md | 2 +- docs/guide/interactive.md | 50 +++++++++++++++++++++++++++++++-- docs/guide/templating.md | 2 +- docs/guide/workspace.md | 58 +++++++++++++++++++++++++++++++++++++-- 4 files changed, 106 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index eed5ffb..98ac3bc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ operations workflows. #### _Features_ - **Task Runner**: Easily define, manage, and run your tasks (called [executables](guide/executable.md)) from the command line. -- **Secret Vault**: Store sensitive secrets in a secure local [vault](guide/vault.md). +- **Secret Vault**: Store sensitive secrets in a secure local [vault](guide/secret.md#vault-setup). - **Template Generator**: Generate executables and workspace scaffolding with [flow file templates](guide/templating.md). - **TUI Library**: Explore and run executables from the interactive and searchable TUI [library](cli/flow_library.md). - **Executable Organizer**: Group, reference, and search for executables by workspace, namespace, verbs, and tags. diff --git a/docs/guide/interactive.md b/docs/guide/interactive.md index a6c9966..0665c4c 100644 --- a/docs/guide/interactive.md +++ b/docs/guide/interactive.md @@ -1,3 +1,49 @@ -coming soon... +## Interactive Configurations -In the meantime, see [flow config](../types/config.md) and [flow config](../cli/flow_config.md). +The interactive TUI can be customized in the [flow config file](../types/config.md). Additionally, +there are several [flow config commands](../cli/flow_config.md) that can be used to change the TUI settings. + +### Changing the log mode + +There are 4 log modes available in the TUI: +- `logfmt`: Includes the log level, timestamp, and log message. +- `text`: Includes just the log message. +- `json`: Includes the log level, timestamp, and log message in JSON format. +- `hidden`: Hides the log messages. + +The default log mode is `logfmt`. Use the following command to change the log mode: + +```shell +flow config set log-mode (logfmt|text|json|hidden) +``` + +`exec` executables can be also configured to use a specific log mode. See the [flowfile configuration](../types/flowfile.md#executableexecexecutabletype) for more information. + +```yaml +executables: + - name: my-task + exec: + logMode: text + cmd: echo "Hello, world!" +``` + +Note: the [flow logs](../cli/flow_logs.md) command will always display logs in `json` mode. + +### Changing the workspace mode + +There are 2 workspace modes available in the TUI: +- `fixed`: The current workspace is fixed to the one you've set with [flow workspace set](../cli/flow_workspace_set.md). +- `dynamic`: The current workspace is determined by your current working directory. If you're in a workspace directory, the TUI will automatically switch to that workspace. Otherwise, the TUI will use the workspace you've set with [flow workspace set](../cli/flow_workspace_set.md). + +See the [workspace guide](workspace.md) for more information on workspaces. + +### Disable the TUI + +In some cases, you may want to disable the interactive TUI (in CI/CD pipelines and containers, for example). +Use the following command will switch all TUI commands to their non-interactive counterparts: + +```shell +flow config set tui false +``` + +Alternatively, you can set the `DISABLE_FLOW_INTERACTIVE` environment variable to `true` to disable the TUI. diff --git a/docs/guide/templating.md b/docs/guide/templating.md index a96e684..0a9a788 100644 --- a/docs/guide/templating.md +++ b/docs/guide/templating.md @@ -1,3 +1,3 @@ -coming soon... +Guide coming soon... In the meantime, see [Template](../types/template.md) and [flow template](../cli/flow_template.md). diff --git a/docs/guide/workspace.md b/docs/guide/workspace.md index d3b940c..dcacc44 100644 --- a/docs/guide/workspace.md +++ b/docs/guide/workspace.md @@ -1,3 +1,57 @@ -coming soon... +Flow is built around [executables](executable.md), which are defined in [flowfiles](../types/flowfile.md) and organized into +directory structures called **workspaces**. Executables can also be grouped across **namespaces** nested within the flowfile trees of these workspaces. -In the meantime, see [FlowFile](../types/workspace.md) and [flow workspace](../cli/flow_workspace.md). +## Workspace Registration + +You can register multiple workspaces with Flow. To do so, use the [flow workspace create](../cli/flow_workspace_create.md) command: + +```shell +# Create a workspace named "my-workspace" in the current directory +flow workspace create my-workspace . +# Create a workspace named "my-workspace" in a specific directory and set it as the current workspace +flow workspace create my-workspace /path/to/directory --set +``` + +When a workspace is created, a [configuration](#workspace-configuration) file is added to the root of the workspace if one does not already exist. + +### Workspace Configuration + +The workspace configuration file is a YAML file that contains the configuration options for the workspace. This file is located in the root directory of the workspace and is named `flow.yaml`. + +For more details about workspace configuration options, see [Workspace](../types/workspace.md). + + +## Changing the Current Workspace + +To change the current workspace, use the [flow workspace set](../cli/flow_workspace_set.md) command: + +```shell +# Set the current workspace to "my-workspace" +flow workspace set my-workspace +``` + +Also see the [workspace mode](interactive.md#changing-the-workspace-mode) documentation for more information on workspace modes. + +## Deleting a Workspace + +To delete a workspace, use the [flow workspace delete](../cli/flow_workspace_delete.md) command: + +```shell +# Delete the workspace named "my-workspace" +flow workspace delete my-workspace +``` + +## Workspace Viewer + +The [flow workspace](../cli/flow_workspace.md) command provides various viewing and management options for workspaces: + +```shell +# View the current workspace +flow workspace view +# View a specific workspace +flow workspace view my-workspace +# List all registered workspaces +flow workspace list +# List all workspaces with a specific tag +flow workspace list --tag my-tag +```