Skip to content

Commit 354b144

Browse files
aloisklinkaloisklink
authoredApr 16, 2024
Merge pull request #12 from Mermaid-Chart/feat/add-mermaid-chart-cli
Add a `@mermaidchart/cli` CLI tool for accessing Mermaid Chart
2 parents 5be5e51 + 480df29 commit 354b144

21 files changed

+1957
-39
lines changed
 

‎.github/workflows/build.yml

+4-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ jobs:
99
strategy:
1010
matrix:
1111
node: ['18.18.x']
12-
pkg: ['sdk']
12+
pkg: ['sdk', 'cli']
1313
runs-on:
1414
labels: ubuntu-latest
1515
steps:
@@ -30,6 +30,9 @@ jobs:
3030
run: |
3131
pnpm install --frozen-lockfile --filter='...${{ matrix.pkg }}'
3232
33+
- name: Lint (if present) ${{ matrix.pkg }}
34+
run: pnpm --if-present --filter='${{ matrix.pkg }}' lint
35+
3336
- name: Test ${{ matrix.pkg }}
3437
run: |
3538
pnpm --filter='${{ matrix.pkg }}' test

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ The OpenAPI YAML file is located at [./openapi.yaml](./openapi.yaml).
1212

1313
- [Javascript/Typescript](./packages/sdk)
1414

15+
## CLI
16+
17+
- [`@mermaidchart/cli` command-line interface](./packages/cli)
18+
1519
## Plugins
1620

1721
- [VSCode (to be migrated here)](https://github.com/Mermaid-Chart/vscode-mermaid-chart/)

‎cSpell.json

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"Cataa",
66
"colour",
77
"Cookiebot",
8+
"gantt",
89
"jsnext",
910
"lintstagedrc",
1011
"mermaidchart",

‎packages/cli/.eslintrc.cjs

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
module.exports = /** @type {import("eslint").Linter.Config} */ ({
2+
root: false, // mono-repo
3+
parser: '@typescript-eslint/parser',
4+
ignorePatterns: ['*.cjs'],
5+
parserOptions: {
6+
ecmaVersion: 2022, // support node v18 features
7+
allowAutomaticSingleRunInference: true,
8+
sourceType: 'module',
9+
project: ['./tsconfig.json'],
10+
tsconfigRootDir: __dirname,
11+
parser: '@typescript-eslint/parser',
12+
},
13+
rules: {
14+
"no-console": ["warn"], // TODO: fix all of these
15+
}
16+
});

‎packages/cli/README.md

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# @mermaidchart/cli
2+
3+
CLI for interacting with https://MermaidChart.com, the platform that makes collaborating with Mermaid diagrams easy!
4+
5+
## Installation
6+
7+
`@mermaidcart/cli` is tested to work with Node.JS v18.18.0 or later.
8+
9+
We recommend installation using [npx](https://docs.npmjs.com/cli/v10/commands/npx)
10+
to automatically download, cache, and run `@mermaidcart/cli`, as it comes with
11+
most Node.JS installations.
12+
13+
```bash
14+
npx @mermaidchart/cli --help
15+
```
16+
17+
## Usage
18+
19+
```bash
20+
npx @mermaidchart/cli <command>
21+
```
22+
23+
Use `--help` to see options!
24+
25+
```bash
26+
npx @mermaidchart/cli --help
27+
```
28+
29+
`@mermaidchart/cli` allows you to easily sync local diagrams with your diagrams
30+
on https://mermaidchart.com.
31+
32+
### `login`
33+
34+
Firstly, go to https://www.mermaidchart.com/app/user/settings and generate an
35+
API key, which you can then setup by running:
36+
37+
```bash
38+
npx @mermaidchart/cli login
39+
```
40+
41+
### `link` an existing Mermaid diagram to MermaidChart.com
42+
43+
You can link a local Mermaid diagram to MermaidChart using:
44+
45+
```bash
46+
npx @mermaidchart/cli link ./path/to/my/mermaid-digram.mmd
47+
```
48+
49+
This will add an `id: xxxx-xxxxx-xxxxx` field to your diagram's YAML frontmatter,
50+
which points to the diagram on MermaidChart.com:
51+
52+
````markdown
53+
```mermaid
54+
---
55+
title: My diagram
56+
id: xxxx-xxxxx-xxxxx # this field is created by @mermaidchart/cli
57+
---
58+
flowchart
59+
x[My Diagram]
60+
```
61+
````
62+
63+
### `push` local changes to MermaidChart.com
64+
65+
Once you've made some local changes, you can `push` your changes to MermaidChart.com
66+
67+
```console
68+
$ npx @mermaidchart/cli push ./path/to/my/mermaid-digram.mmd
69+
✅ - ./path/to/my/mermaid-digram.mmd was pushed
70+
```
71+
72+
### `pull` changes from MermaidChart.com
73+
74+
You can use `pull` to pull down changes from MermaidChart.com.
75+
76+
```console
77+
$ npx @mermaidchart/cli pull ./path/to/my/mermaid-digram.mmd
78+
✅ - ./path/to/my/mermaid-digram.mmd was updated
79+
```
80+
81+
Or use the `--check` flag to throw an error if your local file would have been
82+
updated:
83+
84+
```console
85+
$ npx @mermaidchart/cli pull ./path/to/my/mermaid-digram.mmd
86+
❌ - ./path/to/my/mermaid-digram.mmd would be updated
87+
```
88+
89+
## Contributing
90+
91+
For local development and testing, you can `pnpm dev` to run the CLI,
92+
`pnpm run lint` to run linting, and `pnpm test` to run unit tests.

‎packages/cli/package.json

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
{
2+
"name": "@mermaidchart/cli",
3+
"version": "0.1.0-alpha.0",
4+
"description": "CLI for interacting with https://MermaidChart.com, the platform that makes collaborating with Mermaid diagrams easy",
5+
"main": "index.js",
6+
"bin": {
7+
"mermaid-chart": "dist/cli.js"
8+
},
9+
"//1": "temporarily disable pushing until we finish progress on this",
10+
"private": true,
11+
"engines": {
12+
"node": "^18.18.0 || ^20.0.0"
13+
},
14+
"scripts": {
15+
"dev": "tsx src/cli.ts",
16+
"lint": "eslint src/ && prettier --check src/",
17+
"lint:fix": "eslint --fix src/ && prettier --write src/",
18+
"prepare": "tsc --build tsconfig.json",
19+
"test": "vitest"
20+
},
21+
"type": "module",
22+
"repository": {
23+
"type": "git",
24+
"directory": "packages/cli",
25+
"url": "git+https://github.com/Mermaid-Chart/plugins.git"
26+
},
27+
"keywords": [
28+
"mermaid",
29+
"mermaidchart",
30+
"cli"
31+
],
32+
"author": "Alois Klink <alois@mermaidchart.com> (https://github.com/aloisklink)",
33+
"//2": "TODO: decide on a license once this code is finished",
34+
"license": "UNLICENSED",
35+
"bugs": {
36+
"url": "https://github.com/Mermaid-Chart/plugins/issues"
37+
},
38+
"homepage": "https://github.com/Mermaid-Chart/plugins/tree/main/packages/cli#readme",
39+
"devDependencies": {
40+
"@cspell/eslint-plugin": "^8.0.0",
41+
"@tsconfig/node18": "^18.2.2",
42+
"@tsconfig/strictest": "^2.0.2",
43+
"@types/iarna__toml": "^2.0.5",
44+
"@types/js-yaml": "^4.0.9",
45+
"@types/node": "^18.18.11",
46+
"@typescript-eslint/eslint-plugin": "^6.11.0",
47+
"@typescript-eslint/parser": "^6.11.0",
48+
"eslint": "^8.54.0",
49+
"tsx": "^3.12.8",
50+
"typescript": "^5.2.2",
51+
"vitest": "^0.34.6"
52+
},
53+
"dependencies": {
54+
"@commander-js/extra-typings": "^11.1.0",
55+
"@iarna/toml": "^2.2.5",
56+
"@inquirer/input": "^1.2.14",
57+
"@inquirer/select": "^1.3.1",
58+
"@mermaidchart/sdk": "workspace:^",
59+
"commander": "^11.1.0",
60+
"js-yaml": "^4.1.0"
61+
}
62+
}

‎packages/cli/src/cli.ts

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/usr/bin/env node
2+
3+
import { createCommanderCommand } from './commander.js';
4+
5+
createCommanderCommand()
6+
.parseAsync()
7+
.catch((error) => {
8+
console.error(error); // eslint-disable-line no-console
9+
process.exitCode = 1;
10+
});

0 commit comments

Comments
 (0)
Failed to load comments.