Skip to content

Commit 51d44f0

Browse files
HurricanKaiHurricanKai
authored
CLI docs V0 (windmill-labs#97)
1 parent eda4755 commit 51d44f0

File tree

6 files changed

+10445
-10493
lines changed

6 files changed

+10445
-10493
lines changed

‎docs/advanced/3_cli/index.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Command Line Interface (wmill)
3+
---
4+
5+
# Command Line Interface (wmill)
6+
7+
The wmill CLI allows you to interact with Windmill instances right from your
8+
terminal.
9+
10+
You can also use it for various automation tasks, including
11+
[syncing](./syncing.md) folders &
12+
[github-repositories](./syncing.md#stateful-sycing)
13+
14+
See [installation](./installation.md) for getting started.

‎docs/advanced/3_cli/installation.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: CLI Installation
3+
---
4+
5+
# Installation
6+
7+
Simply install the wmill cli using
8+
`deno install --unstable -A https://deno.land/x/wmill/main.ts`. You will need
9+
[deno installed](https://deno.land/manual@v1.30.3/getting_started/installation).
10+
11+
## Upgrade
12+
13+
Running `wmill upgrade` will upgrade your installation to the latest version.
14+
15+
## Completion
16+
17+
The CLI comes with completions out of the box via `wmill completions <shell>`.
18+
(Via [cliffy](https://cliffy.io/))
19+
20+
### Bash
21+
22+
To enable bash completions add the following line to your `~/.bashrc`:
23+
24+
```
25+
source <(wmill completions bash)
26+
```
27+
28+
### Fish
29+
30+
To enable fish completions add the following line to your
31+
`~/.config/fish/config.fish`:
32+
33+
```
34+
source (wmill completions fish | psub)
35+
```
36+
37+
### Zsh
38+
39+
To enable zsh completions add the following line to your `~/.zshrc`:
40+
41+
```
42+
source <(wmill completions zsh)
43+
```

‎docs/advanced/3_cli/syncing.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: CLI Syncing
3+
---
4+
5+
# Syncing
6+
7+
Syncronizing folders & git repositories to a windmill instance is made easy
8+
using the wmill CLI. Syncing operations are behind the `wmill sync` subcommand.
9+
10+
## Example Repos
11+
12+
We provide example repos for various use cases:
13+
14+
- Mirroring/Backup of a remote:
15+
[windmill-backup-example](https://github.com/windmill-labs/windmill-backup-example)
16+
- Pushing to a remote only:
17+
[windmill-push-example](https://github.com/windmill-labs/windmill-push-example)
18+
- Syncing with a remote:
19+
[windmill-backup-example](https://github.com/windmill-labs/windmill-sync-example)
20+
21+
## Raw Syncing
22+
23+
Raw syncing is a one-off operation with no state maintained. It's best used for
24+
making backups, cloning a complete workspace, and similar one-off operations.
25+
26+
Raw syncing is done using `wmill sync pull --raw` & `wmill sync push --raw`
27+
28+
### Pulling
29+
30+
`wmill sync pull --raw` will simply pull all files from the currently
31+
[selected workspace](./workspace-management.md#selected-workspace) and store
32+
them in the current folder. Overwrites will not prompt the user. Make sure you
33+
are in the correct folder or you may loose data.
34+
35+
### Pushing
36+
37+
`wmill sync push --raw` will simply push all local files to the currently
38+
[selected workspace](./workspace-management.md#selected-workspace), creating or
39+
updating the remote equivalents.
40+
41+
### Operation
42+
43+
## Stateful Syncing
44+
45+
Stateful syncing is best used when you want to continuously syncronize a folder
46+
or git(hub) repository with a windmill instance. The CLI will automatically
47+
maintain state for you and ensure modifications that happen concurrently on the
48+
remote and locally stay in sync.
49+
50+
### Initializing
51+
52+
To get started, run `wmill sync init` this will initialize the current folder
53+
with a `.wmill` folder, where internal state will be stored, and a
54+
`.wmillignore`, which you can use to ignore some files.
55+
56+
:::caution
57+
58+
`wmill sync init` will store the
59+
[selected workspace](./workspace-management.md#selected-workspace) as part of
60+
the state. Make sure to select the correct workspace.
61+
62+
:::
63+
64+
### Pulling
65+
66+
Pulling with `wmill sync pull` will first update the internal state, and then
67+
generate a diff between your local files and this state, only updating the
68+
actually modified files. Possible conflicts will warn the user.
69+
70+
### Pushing
71+
72+
Pushing with `wmill sync push` will first update the internal state, and then
73+
generate a diff between your local files and this state, only sending the
74+
relevant local updates to the remote server.
75+
76+
:::tip
77+
78+
Run `wmill sync pull` right after `push` if you intend to keep updating the
79+
folder. This will ensure your folder stays in sync.
80+
81+
:::

‎docs/advanced/3_cli/workspace-management.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: CLI Workspace Management
3+
---
4+
5+
# Workspace Management
6+
7+
The wmill CLI is capable of handling working with many remotes & workspaces.
8+
Each combination of remote & workspace is registered with together with a name
9+
locally using `wmill workspace add`.
10+
11+
## List workspaces
12+
13+
`wmill workspace` will print a table of all the locally known workspaces, the
14+
currently [selected workspace](#selected-workspace) is <ins>underlined</ins>.
15+
16+
## Adding a workspace
17+
18+
Either use the dialog using just `wmill workspace add`, or use
19+
`wmill workspace add <name> <workspace_id> <remote_url>` or even provide a token
20+
using `--token` to entirely skip the dialogue.
21+
22+
The new workspace will automatically be [switched](#switching-selection) to
23+
24+
## Selected Workspace
25+
26+
The currently selected workspace will be used for all operations. This workspace
27+
is <ins>underlined</ins> in the [list of workspaces](#list-workspaces).
28+
29+
### Switching Selection
30+
31+
`wmill workspace switch <name>` can be used to switch the currently selected
32+
workspace.
33+
34+
## Removing a workspace
35+
36+
`wmill remove <name>` can be used to delete a workspace from the list of
37+
workspaces.

‎docs/intro.md

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ All code is not made equal and can be split in 2 categories:
1111
- **Boilerplate**: all the rest is boilerplate, be it UI and frontends that
1212
allow you to call the code above, api calls to external services, error
1313
handling, retries, logic to make your code scalable, dependency management,
14-
CI/CD, managing secrets, schedule, permissions, authentification, etc.
15-
That code is boilerplate because it _feels_ like you shouldn't have to
16-
reinvent the wheel, over and over again.
14+
CI/CD, managing secrets, schedule, permissions, authentification, etc. That
15+
code is boilerplate because it _feels_ like you shouldn't have to reinvent the
16+
wheel, over and over again.
1717

1818
Many services labels themselves as **no-code** or **low-code**, and they address
1919
indeed the challenge of getting rid of the boilerplate and provide a
@@ -23,12 +23,15 @@ flexibility of code** as they either hide it completely, or only allow it under
2323
restricted forms.
2424

2525
Windmill is different:
26-
- it allows building **internal tools through code** much faster, without sacrificing on one side
27-
visibility and intuitivity and on the other side, control, reliability, performance, flexibility and scalability
28-
- it **empowers semi-technical users** to access and edit that code without being overwhelmed
29-
by the usual barriers to entry (git, IDE, local environments, secrets managements, etc.)
30-
- it is compatible with senior/staff software engineers **high standards for production-grade** yet flexible
31-
yet customizable with code.
26+
27+
- it allows building **internal tools through code** much faster, without
28+
sacrificing on one side visibility and intuitivity and on the other side,
29+
control, reliability, performance, flexibility and scalability
30+
- it **empowers semi-technical users** to access and edit that code without
31+
being overwhelmed by the usual barriers to entry (git, IDE, local
32+
environments, secrets managements, etc.)
33+
- it is compatible with senior/staff software engineers **high standards for
34+
production-grade** yet flexible yet customizable with code.
3235

3336
Windmill embeds:
3437

@@ -40,14 +43,15 @@ Windmill embeds:
4043
even [SQL](./getting_started/0_scripts_quickstart/5_sql_quickstart/index.md)
4144
from a self-managed job queue, at scale, with any dependency, no overhead, and
4245
minimal cold start
43-
- a **parser that will infer the dependencies and arguments** from the code itself
44-
and generate **lockfiles** and **input specs**
45-
- the _lockfile_ allows the script being deployed to maintain exactly the
46-
same set of versioned dependencies forever
47-
- the in _input spec_ (which is actually a JSON schema) is used to generate a minimal
48-
UI automatically for both using the script as a standalone compute or as a
49-
step of a Flow
50-
- a powerful **web IDE** to write Scripts with autocompletion and syntax checking
46+
- a **parser that will infer the dependencies and arguments** from the code
47+
itself and generate **lockfiles** and **input specs**
48+
- the _lockfile_ allows the script being deployed to maintain exactly the same
49+
set of versioned dependencies forever
50+
- the in _input spec_ (which is actually a JSON schema) is used to generate a
51+
minimal UI automatically for both using the script as a standalone compute
52+
or as a step of a Flow
53+
- a powerful **web IDE** to write Scripts with autocompletion and syntax
54+
checking
5155
- a **low-code builder and workflow engine** to build and run complex
5256
[Flows](./getting_started/6_flows_quickstart/index.md) by composing your
5357
custom scripts and generic scripts shared on
@@ -76,8 +80,8 @@ Windmill embeds:
7680
Flows. Combined with state storage, it can be used to watch for external
7781
events - for example triggering a Flow only if the external state is different
7882
from the one stored previously
79-
- a [CLI](https://github.com/windmill-labs/windmill/tree/main/cli) and GitHub
80-
Actions for **GitHub** and local based developement and code management.
83+
- a [CLI](./advanced/3_cli/index.md) and GitHub Actions for **GitHub** and local
84+
based developement and code management.
8185

8286
On top of all these, you'll get a splendid community and a responsive support
8387
team to attend you in your journey.
@@ -127,10 +131,12 @@ with:
127131
both **heavily code-based**, have **no low-code builders** for the flows, are
128132
**complex to set up** and operate, and do not allow to share scripts easily or
129133
build UIs.
130-
- _Retool_ for building **admin panels**, and its other open-source alternatives:
131-
_Tooljet_, _Appsmith_.
134+
- _Retool_ for building **admin panels**, and its other open-source
135+
alternatives: _Tooljet_, _Appsmith_.
132136
- _Airplane_ and _Superblocks_ have comparable set of features, but **not
133137
open-source nor self-hostable**, **limited workflow** engines, **not made for
134138
scalability** and have **no open APIs**.
135139

136-
You will find more details on our view over our space and competitors in the [Windmill compared to its peers page](https://docs.windmill.dev/docs/misc/windmill_compared_to_peers) page.
140+
You will find more details on our view over our space and competitors in the
141+
[Windmill compared to its peers page](https://docs.windmill.dev/docs/misc/windmill_compared_to_peers)
142+
page.

0 commit comments

Comments
 (0)