Skip to content

Commit

Permalink
docs: add workspace and interactive documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
jahvon committed Oct 6, 2024
1 parent d8e01b4 commit a1537b6
Show file tree
Hide file tree
Showing 4 changed files with 106 additions and 6 deletions.
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ operations workflows.
#### _Features_ <!-- {docsify-ignore} -->

- **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.
Expand Down
50 changes: 48 additions & 2 deletions docs/guide/interactive.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion docs/guide/templating.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
coming soon...
Guide coming soon...

In the meantime, see [Template](../types/template.md) and [flow template](../cli/flow_template.md).
58 changes: 56 additions & 2 deletions docs/guide/workspace.md
Original file line number Diff line number Diff line change
@@ -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
```

0 comments on commit a1537b6

Please sign in to comment.