Skip to content

Commit 8557fe2

Browse files
MihalyToth20MihalyToth20
committed
feat: added and improved the docsify content
1 parent d692c80 commit 8557fe2

20 files changed

+354
-209
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
+==================================================================================================+
1414
```
1515

16-
[📚 **View Full CLI Documentation**](docs/README.md)
16+
[📚 **View Full CLI Documentation**](https://calycode.com/cli/docs)
1717

1818
# xano tools
1919

‎docs/README.md‎

Lines changed: 149 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,152 @@
1-
# @calycode/cli (Caly-Xano CLI) Command Reference
1+
# @calycode/cli Docs
22

33
Supercharge your Xano workflow: automate backups, docs, testing, and version control—no AI guesswork, just reliable, transparent dev tools.
44

5-
## Table of Contents
6-
7-
- [xano - the core command](xano.md)
8-
9-
### Commands
10-
- [`setup`](commands/setup.md)
11-
- [`switch-context`](commands/switch-context.md)
12-
- [`generate-oas`](commands/generate-oas.md)
13-
- [`serve-oas`](commands/serve-oas.md)
14-
- [`generate-code`](commands/generate-code.md)
15-
- [`generate-repo`](commands/generate-repo.md)
16-
- [`generate-xs-repo`](commands/generate-xs-repo.md)
17-
- [`registry-add`](commands/registry-add.md)
18-
- [`registry-scaffold`](commands/registry-scaffold.md)
19-
- [`serve-registry`](commands/serve-registry.md)
20-
- [`export-backup`](commands/export-backup.md)
21-
- [`restore-backup`](commands/restore-backup.md)
22-
- [`run-test`](commands/run-test.md)
23-
- [`current-context`](commands/current-context.md)
24-
25-
Need further help? Visit [GitHub](https://github.com/calycode/xano-tools) or reach out to Mihály Tóth on [State Change](https://statechange.ai/) or [Snappy Community](https://www.skool.com/@mihaly-toth-2040?g=snappy)
5+
[//]: # 'ASCII art block for docs link'
6+
7+
```
8+
+==================================================================================================+
9+
| |
10+
| ██████╗ █████╗ ██╗ ██╗ ██╗ ██╗ ██╗ █████╗ ███╗ ██╗ ██████╗ ██████╗██╗ ██╗ |
11+
| ██╔════╝██╔══██╗██║ ╚██╗ ██╔╝ ╚██╗██╔╝██╔══██╗████╗ ██║██╔═══██╗ ██╔════╝██║ ██║ |
12+
| ██║ ███████║██║ ╚████╔╝█████╗╚███╔╝ ███████║██╔██╗ ██║██║ ██║ ██║ ██║ ██║ |
13+
| ██║ ██╔══██║██║ ╚██╔╝ ╚════╝██╔██╗ ██╔══██║██║╚██╗██║██║ ██║ ██║ ██║ ██║ |
14+
| ╚██████╗██║ ██║███████╗██║ ██╔╝ ██╗██║ ██║██║ ╚████║╚██████╔╝ ╚██████╗███████╗██║ |
15+
| ╚═════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═════╝╚══════╝╚═╝ |
16+
| |
17+
+==================================================================================================+
18+
```
19+
20+
[📚 **View Full CLI Documentation**](https://calycode.com/cli/docs)
21+
22+
# xano tools
23+
24+
**_(Work In Progress)_**
25+
26+
---
27+
28+
**A set of tools to improve dev experience with Xano, especially for teams where clarity, transparency, and version control is important. Furthermore, this CLI should help automate currently manual apsects of Xano. Why a CLI when we have AI? I am bullish on the AI, but in all honesty using AI so much without proper human control can cause a lot of issues. The idea behind this CLI is to reduce the need of reliance on AI and that we have our most crucial parts (version control, documentation, testing, code-generation, opinionated rules, etc.) in place in any case, environment, system, either in part of a git provider or local system. The goal is to make it flexible and if there's need, then obiously LLM-ready.**
29+
30+
---
31+
32+
## 🚀 Quick Start
33+
34+
```
35+
# 1. Clone the repo
36+
37+
# 2. Install dependencies
38+
pnpm install
39+
40+
# 3. Build the CLI
41+
pnpm build:packages
42+
43+
# 4. Run any command
44+
xano
45+
```
46+
47+
> _(Optional)_ If you want the CLI globally available during development:
48+
> ```
49+
> pnpm link
50+
> ```
51+
> **Note:** If you use `pnpm link`, remember to `pnpm unlink --global` when done to avoid version confusion.
52+
53+
! See the [documentation](/docs/README.md) for available commands and arguments.
54+
55+
## 🤖 Using in GitHub Actions
56+
57+
You can use this CLI as a GitHub Action to automate your Xano workflows.
58+
59+
Here is an example job that checks out your repository and uses the local composite action (`./dist/actions/master-action.yml`), which in turn securely downloads and runs the Caly-Xano CLI as npm package via the npx command.
60+
61+
```yaml
62+
jobs:
63+
sync:
64+
runs-on: ubuntu-latest
65+
66+
steps:
67+
- uses: actions/checkout@v4
68+
69+
# 1. Setup Node.js and authenticate to the npm registry
70+
- uses: actions/setup-node@v4
71+
with:
72+
node-version: '20'
73+
registry-url: 'https://registry.npmjs.org'
74+
75+
# 2. Use the Xano CLI Action from your repository
76+
# This composite action handles setup and (multiple or single) command execution by calling the published npm package.
77+
- name: Run Caly-Xano Commands
78+
uses: ./dist/actions/master-action.yml
79+
with:
80+
# Xano Instance name, used to identify the created configuration during command execution
81+
instance-name: 'production'
82+
instance-url: ${{ secrets.XANO_URL }}
83+
# Xano Metadata API token. Make sure to set it up as a secret
84+
api-token: ${{ secrets.XANO_API_TOKEN }}
85+
version: 'latest' # or a specific version like '0.1.1'
86+
# You can specify multiple commands in new lines and the action will execute them in order.
87+
# See the [documentation](/docs/README.md) for command docs.
88+
run: |
89+
generate-oas --all
90+
```
91+
92+
---
93+
94+
### Xano Registry **(WIP)**
95+
96+
I have been astonished by the shadcn/ui CLI and the core principles of code distribution implemented in that tool. While that is primarily for frontend developers, their attempt to generalise their registry pointed me into the direction where I have started rebuilding a registry system for Xano powered by `xanoscript`. The reason for this is to overcome the bugs of Xano Snippets, avoid dependency of external providers of Xano Actions and in general to allow any team to build their own registries. These registries should also server as guidance for LLMs to eventually start generating more and more reliable `xanoscript`.
97+
98+
<details>
99+
<summary>How to use the registry feature?</summary>
100+
101+
1. Scaffold the registry or build it manually by obeying the schemas (https://calycode.com/schemas/registry/registry.json).
102+
```
103+
xano registry-scaffold
104+
```
105+
2. Serve your registry locally or host it on an object storage (or [advanced] recreate a Xano api that would deliver the required JSON objects on demand --> this could allow you to add auth as well)
106+
107+
```
108+
xano serve-registry
109+
```
110+
111+
3. Use the registry and it's content in `xano`
112+
```
113+
xano registry-add --components <coma separated component names> --registry <registry url>
114+
```
115+
116+
> **Notes:**
117+
> Currently there is no way of automatically build out the registry from a collection of `xanoscript` files, so this is why
118+
> it is important to always keep the registry/definitions/index.json and the individual definition files in sync.
119+
> Currently there is theoretic support for registry:function and registry:table components, registry:query but registry:snippet is planned.
120+
> With the registry:snippet I aim to have a shot at fixing Xano's Snippets and make it searchable and reusable by also LLMs.
121+
122+
</details>
123+
124+
---
125+
126+
## 🚧 CLI Status
127+
128+
> **WORK IN PROGRESS:**
129+
> Expect frequent _(potentially breaking)_ changes!
130+
131+
---
132+
133+
## ✔️ What Works Now?
134+
135+
- [x] Allow multi-user multi workspace setup.
136+
- [x] Add context-switching to the configuration options.
137+
- [x] Generate improved **OpenAPI sepcification + Scalar** Reference html (hostable anywhere and viewable locally).
138+
- [x] **Generate code** from the backend API groups, powered by openapi tools generator CLI.
139+
- [x] **Processing Xano** queries, functions, and tables **into a browsable repo** structure
140+
- [x] **Export and restore backups** via Metadata API
141+
- [x] **Scaffolding a registry** of reusable Xano components
142+
- [x] Exporting all available `xanoscript` from your instance via metadata API _*(important note: not all pieces of logic can be exported via metadata API, this especially is fragile on older and bigger instances)_.
143+
- [x] Adding components to Xano from a registry (only functions, tables, queries for now)
144+
- [ ] Automated test runner with assertion configuration
145+
- [ ] Linting with custom rulesets
146+
147+
---
148+
149+
**Contributions, feedback, and ideas are welcome!** Open an issue, or reach out to me on [State Change](https://statechange.ai/) or [Snappy Community](https://www.skool.com/@mihaly-toth-2040?g=snappy).
150+
151+
152+
Need further help? Visit [GitHub](https://github.com/calycode/xano-tools) or reach out to Mihály Tóth on [State Change](https://statechange.ai/) or [Snappy Community](https://www.skool.com/@mihaly-toth-2040?g=snappy)

‎docs/commands/current-context.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# `current-context` Command
1+
# current-context
2+
```sh
3+
xano current-context [options]
4+
```
25
### Options
36

47

‎docs/commands/export-backup.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
1-
# `export-backup` Command
2-
> Backup Xano Workspace via Metadata API
1+
# export-backup
2+
> #### Backup Xano Workspace via Metadata API
3+
4+
```sh
5+
xano export-backup [options]
6+
```
37
### Options
48

59
#### --instance <instance>
@@ -18,16 +22,12 @@ Usage: xano export-backup [options]
1822
Backup Xano Workspace via Metadata API
1923

2024
Options:
21-
--instance <instance> The instance name. This is used to fetch
22-
the instance configuration. The value
23-
provided at the setup command.
24-
--workspace <workspace> The workspace name. This is used to fetch
25-
the workspace configuration. Same as on
26-
Xano interface.
27-
--branch <branch> The branch name. This is used to select the
28-
branch configuration. Same as on Xano
29-
Interface.
30-
--print-output-dir Expose usable output path for further
31-
reuse.
25+
--instance <instance> The instance name. This is used to fetch the instance
26+
configuration. The value provided at the setup command.
27+
--workspace <workspace> The workspace name. This is used to fetch the workspace
28+
configuration. Same as on Xano interface.
29+
--branch <branch> The branch name. This is used to select the branch
30+
configuration. Same as on Xano Interface.
31+
--print-output-dir Expose usable output path for further reuse.
3232
-h, --help display help for command
3333
```

‎docs/commands/generate-code.md‎

Lines changed: 20 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
1-
# `generate-code` Command
2-
> Create a library based on the OpenAPI specification. If the openapi specification has not yet been generated, this will generate that as well as the first step.
1+
# generate-code
2+
> #### Create a library based on the OpenAPI specification. If the openapi specification has not yet been generated, this will generate that as well as the first step.
3+
4+
```sh
5+
xano generate-code [options]
6+
```
37
### Options
48

59
#### --instance <instance>
@@ -25,32 +29,25 @@
2529
```sh
2630
Usage: xano generate-code [options]
2731

28-
Create a library based on the OpenAPI specification. If the openapi
29-
specification has not yet been generated, this will generate that as
30-
well as the first step.
32+
Create a library based on the OpenAPI specification. If the openapi specification has not
33+
yet been generated, this will generate that as well as the first step.
3134

3235
Options:
33-
--instance <instance> The instance name. This is used to fetch
34-
the instance configuration. The value
35-
provided at the setup command.
36-
--workspace <workspace> The workspace name. This is used to fetch
37-
the workspace configuration. Same as on
38-
Xano interface.
39-
--branch <branch> The branch name. This is used to select the
40-
branch configuration. Same as on Xano
41-
Interface.
36+
--instance <instance> The instance name. This is used to fetch the instance
37+
configuration. The value provided at the setup command.
38+
--workspace <workspace> The workspace name. This is used to fetch the workspace
39+
configuration. Same as on Xano interface.
40+
--branch <branch> The branch name. This is used to select the branch
41+
configuration. Same as on Xano Interface.
4242
--group <name> API group name. Same as on Xano Interface.
43-
--all Regenerate for all API groups in the
44-
workspace / branch of the current context.
45-
--print-output-dir Expose usable output path for further
46-
reuse.
43+
--all Regenerate for all API groups in the workspace / branch of the
44+
current context.
45+
--print-output-dir Expose usable output path for further reuse.
4746
--generator <generator> Generator to use, see all options at:
4847
https://openapi-generator.tech/docs/generators
49-
--args <args> Additional arguments to pass to the
50-
generator. See
48+
--args <args> Additional arguments to pass to the generator. See
5149
https://openapi-generator.tech/docs/usage#generate
52-
--debug Specify this flag in order to allow
53-
logging. Logs will appear in output/_logs.
54-
Default: false
50+
--debug Specify this flag in order to allow logging. Logs will appear in
51+
output/_logs. Default: false
5552
-h, --help display help for command
5653
```

‎docs/commands/generate-oas.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
1-
# `generate-oas` Command
2-
> Update and generate OpenAPI spec(s) for the current context.
1+
# generate-oas
2+
> #### Update and generate OpenAPI spec(s) for the current context.
3+
4+
```sh
5+
xano generate-oas [options]
6+
```
37
### Options
48

59
#### --instance <instance>
@@ -22,19 +26,15 @@ Usage: xano generate-oas [options]
2226
Update and generate OpenAPI spec(s) for the current context.
2327

2428
Options:
25-
--instance <instance> The instance name. This is used to fetch
26-
the instance configuration. The value
27-
provided at the setup command.
28-
--workspace <workspace> The workspace name. This is used to fetch
29-
the workspace configuration. Same as on
30-
Xano interface.
31-
--branch <branch> The branch name. This is used to select the
32-
branch configuration. Same as on Xano
33-
Interface.
29+
--instance <instance> The instance name. This is used to fetch the instance
30+
configuration. The value provided at the setup command.
31+
--workspace <workspace> The workspace name. This is used to fetch the workspace
32+
configuration. Same as on Xano interface.
33+
--branch <branch> The branch name. This is used to select the branch
34+
configuration. Same as on Xano Interface.
3435
--group <name> API group name. Same as on Xano Interface.
35-
--all Regenerate for all API groups in the
36-
workspace / branch of the current context.
37-
--print-output-dir Expose usable output path for further
38-
reuse.
36+
--all Regenerate for all API groups in the workspace / branch of the
37+
current context.
38+
--print-output-dir Expose usable output path for further reuse.
3939
-h, --help display help for command
4040
```

‎docs/commands/generate-repo.md‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
1-
# `generate-repo` Command
2-
> Process Xano workspace into repo structure
1+
# generate-repo
2+
> #### Process Xano workspace into repo structure
3+
4+
```sh
5+
xano generate-repo [options]
6+
```
37
### Options
48

59
#### --input <file>
@@ -26,18 +30,13 @@ Process Xano workspace into repo structure
2630
Options:
2731
--input <file> workspace yaml file
2832
--output <dir> output directory (overrides config)
29-
--instance <instance> The instance name. This is used to fetch
30-
the instance configuration. The value
31-
provided at the setup command.
32-
--workspace <workspace> The workspace name. This is used to fetch
33-
the workspace configuration. Same as on
34-
Xano interface.
35-
--branch <branch> The branch name. This is used to select the
36-
branch configuration. Same as on Xano
37-
Interface.
38-
--print-output-dir Expose usable output path for further
39-
reuse.
40-
--fetch Specify this if you want to fetch the
41-
workspace schema from Xano
33+
--instance <instance> The instance name. This is used to fetch the instance
34+
configuration. The value provided at the setup command.
35+
--workspace <workspace> The workspace name. This is used to fetch the workspace
36+
configuration. Same as on Xano interface.
37+
--branch <branch> The branch name. This is used to select the branch
38+
configuration. Same as on Xano Interface.
39+
--print-output-dir Expose usable output path for further reuse.
40+
--fetch Specify this if you want to fetch the workspace schema from Xano
4241
-h, --help display help for command
4342
```

0 commit comments

Comments
 (0)