---
url: /quick-start.md
---
# Quick Start

This guide shows how to build OpenMinutes from source, configure authentication, and run the first list, export, upload, and delete workflow.

## Prerequisites

* Go toolchain installed locally.
* An authenticated Feishu/Lark account that can access Feishu/Lark Minutes.
* A valid browser `Cookie` header for the Feishu/Lark Minutes web session.

Do not commit real cookies, HAR files, or personal config files. Treat the cookie like a session secret.

## Build From Source

From the repository root:

```sh
go build -o ./openminutes .
./openminutes --help
```

You can either run the local binary with `./openminutes` or place it on your `PATH` and run `openminutes`.

## Create Configuration

Commands that call Feishu/Lark APIs require a config file. OpenMinutes creates a template automatically the first time a config-backed command runs.

The default help text points to:

```txt
~/.config/openminutes/config.toml
```

When `XDG_CONFIG_HOME` is set, OpenMinutes uses:

```txt
$XDG_CONFIG_HOME/openminutes/config.toml
```

You can also choose an explicit path:

```sh
openminutes --config ./config.toml list
```

## Configure Authentication

Create or edit the config file:

```toml
base_url = "https://meetings.feishu.cn"
space_base_url = "https://internal-api-space.feishu.cn"
cookie = "your browser Cookie header"
```

Config fields:

| Field | Required | Description |
| --- | --- | --- |
| `base_url` | No | Feishu/Lark Minutes web base URL. Defaults to `https://meetings.feishu.cn` when empty. |
| `space_base_url` | No | Feishu/Lark Minutes space API base URL. Defaults to `https://internal-api-space.feishu.cn` when empty. |
| `cookie` | Yes | Browser `Cookie` header from an authenticated Feishu/Lark Minutes session. |

To obtain the cookie, sign in to Feishu/Lark in a browser, open the browser developer tools, inspect a request to the Minutes site, and copy the request `Cookie` header into your local config.

## Environment Overrides

Environment variables override the config file:

```sh
export OPENMINUTES_BASE_URL="https://meetings.feishu.cn"
export OPENMINUTES_SPACE_BASE_URL="https://internal-api-space.feishu.cn"
export OPENMINUTES_COOKIE="your browser Cookie header"
```

Supported variables:

| Variable | Overrides |
| --- | --- |
| `OPENMINUTES_BASE_URL` | `base_url` |
| `OPENMINUTES_SPACE_BASE_URL` | `space_base_url` |
| `OPENMINUTES_COOKIE` | `cookie` |

An empty `OPENMINUTES_COOKIE` still overrides the file value and causes validation to fail.

## First Workflow

List the first page of Minutes:

```sh
openminutes list
```

Export a transcript to stdout:

```sh
openminutes get <token>
```

Export a subtitle file without overwriting an existing file:

```sh
openminutes get <token> --file_type srt --speaker --timestamp -O meeting.srt
```

Upload a supported media file:

```sh
openminutes upload ./meeting.mp4
```

Move a Minute to trash:

```sh
openminutes delete <token> --yes
```

Permanently delete a Minute after moving it to trash:

```sh
openminutes delete <token> --yes --destroy
```

## Common Global Flags

| Flag | Description |
| --- | --- |
| `--config <path>` | Load a specific TOML config file. |
| `--verbose` | Enable debug logging on stderr. |
| `-h, --help` | Show command help. |
| `-v, --version` | Print the OpenMinutes version. |

## Safety Notes

* `delete` always requires `--yes`.
* `delete --destroy` performs permanent deletion after moving the Minute to trash.
* `get -O` creates files exclusively and never overwrites an existing output path.
* Store cookies only in local files or secret managers with appropriate permissions.

---

---
url: /cli/openminutes.md
---
# `openminutes`

## Purpose

`openminutes` is the root command for the OpenMinutes CLI. It provides global flags, version output, command discovery, and shell completion entry points.

Project guidance:

* Repository: <https://github.com/openminutes/openminutes>
* License: `GPL-3.0-only`
* LLM docs: <https://openminutes.duckduckapp.com/llms.txt> and <https://openminutes.duckduckapp.com/llms-full.txt>
* Quick start: <https://openminutes.duckduckapp.com/quick-start.html>

Commands that call Feishu/Lark APIs load configuration and require a valid authentication cookie. The root help and completion commands do not require configuration.

## Usage

```sh
openminutes [command]
```

## Commands

| Command | Purpose |
| --- | --- |
| `openminutes list` | List Minutes from the current account. |
| `openminutes get TOKEN` | Export text from a Minute. |
| `openminutes upload FILE` | Upload media to Minutes for transcription. |
| `openminutes delete TOKEN...` | Delete one or more Minutes from the current account. |
| `openminutes completion` | Generate shell completion scripts. |
| `openminutes help [command]` | Show help for a command. |

## Global Flags

| Flag | Description |
| --- | --- |
| `--config string` | Config file path. The help default is `~/.config/openminutes/config.toml`. |
| `--verbose` | Enable verbose debug logging on stderr. |
| `-h, --help` | Show help. |
| `-v, --version` | Print the version and exit. |

## Examples

```sh
openminutes --help
openminutes --version
openminutes --config ./config.toml list
openminutes --verbose list --json
```

## Output

`openminutes --help` prints project guidance links, licensing information, available commands, and global flags.

`openminutes --version` prints:

```txt
openminutes version <version>
```

Development builds print `dev` as the version.

## Errors And Notes

* There is no standalone `openminutes version` command. Version output is exposed through `-v, --version`.
* Config-backed commands validate `base_url`, `space_base_url`, and `cookie` before calling Feishu/Lark APIs.
* Use `--verbose` when debugging config loading, validation, or API calls.

---

---
url: /cli/list.md
---
# `openminutes list`

## Purpose

List Minutes from the authenticated Feishu/Lark account.

By default, `list` requests one page and prints a follow-up command when another page is available. Use `--timestamp` to continue from that page, or `--all` to follow pagination automatically.

## Usage

```sh
openminutes list [flags]
```

## Arguments

`list` does not accept positional arguments.

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| `--size int` | `20` | Number of Minutes to request per page. Must be greater than `0`. |
| `--timestamp int` | `0` | Pagination timestamp to start from. Must be greater than or equal to `0`. |
| `--json` | `false` | Print structured JSON instead of plain rows. |
| `--all` | `false` | Follow pagination and list all Minutes, starting from `--timestamp` when provided. |

Global flags such as `--config` and `--verbose` are also available.

## Examples

```sh
openminutes list
openminutes list --size 50 --timestamp 1710000000
openminutes list --all --json
openminutes --config ./config.toml list --json
```

## Output

Plain output starts with the row format, then prints one row per Minute:

```txt
Columns: token name URL
m_abc123 Weekly sync https://meetings.feishu.cn/minutes/m_abc123

Next page: openminutes list --size 20 --timestamp 1710000000
Get content: openminutes get <token>
```

If there are no results, the command prints:

```txt
No minutes found.
```

JSON output has this shape:

```json
{
  "items": [
    {
      "object_token": "m_abc123",
      "object_type": 1,
      "topic": "Weekly sync",
      "url": "https://meetings.feishu.cn/minutes/m_abc123",
      "media_type": "video",
      "owner_name": "Ada",
      "duration": 1800,
      "share_time": 1710000000,
      "start_time": 1710000000,
      "stop_time": 1710001800,
      "create_time": 1710000000,
      "status": 0
    }
  ],
  "has_more": true,
  "next_timestamp": 1710000000
}
```

When `--all` is used, OpenMinutes returns all collected items and does not print a next-page command in plain output.

## Errors And Notes

* Requires a valid config and cookie.
* `--size 0` or a negative size fails before the API call.
* A negative `--timestamp` fails before the API call.
* If a list item has no topic, plain output prints `(untitled)`.
* If a list item has no URL, OpenMinutes builds one from `base_url` and the object token.

---

---
url: /cli/get.md
---
# `openminutes get`

## Purpose

Export one Minute as transcript text or subtitles.

The exported content is printed to stdout by default. Use `-O, --output` to write it to a file. Output files are created exclusively and existing files are never overwritten.

## Usage

```sh
openminutes get TOKEN [flags]
```

## Arguments

| Argument | Description |
| --- | --- |
| `TOKEN` | Required object token for the Minute to export. Exactly one token is accepted. |

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| `--file_type string` | `txt` | Export format. Supported values are `txt` and `srt`. |
| `--speaker` | `false` | Include speaker names in the exported text. |
| `--timestamp` | `false` | Include timestamps in the exported text. |
| `-O, --output string` | empty | Write exported content to this file path. |
| `--json` | `false` | Print structured JSON instead of plain text or the default saved-file message. |

Global flags such as `--config` and `--verbose` are also available.

## Examples

```sh
openminutes get m_abc123
openminutes get m_abc123 --json
openminutes get m_abc123 --file_type srt --speaker --timestamp -O meeting.srt
openminutes get m_abc123 -O transcript.txt --json
```

## Output

Without `--output`, plain output is the exported content. OpenMinutes adds a trailing newline when the exported content does not already end with one.

With `--output`, plain output confirms the saved file:

```txt
Saved m_abc123 to meeting.srt
```

With `--json` and no output file, the exported content is included inline:

```json
{
  "object_token": "m_abc123",
  "file_type": "txt",
  "speaker": false,
  "timestamp": false,
  "bytes": 128,
  "content": "Transcript content"
}
```

With `--json` and `--output`, the content is written to disk and the JSON contains metadata:

```json
{
  "object_token": "m_abc123",
  "file_type": "srt",
  "speaker": true,
  "timestamp": true,
  "bytes": 256,
  "output_path": "meeting.srt"
}
```

## Errors And Notes

* Requires a valid config and cookie.
* `TOKEN` is required and must not be blank.
* Only one token is accepted.
* `--file_type` must be `txt` or `srt`.
* If `--output` is passed with an empty value, the command fails before the API call.
* If the output path already exists, the command fails before the API call.
* If writing the output file fails, OpenMinutes removes the partial file.

---

---
url: /cli/upload.md
---
# `openminutes upload`

## Purpose

Upload one local audio or video file to Feishu/Lark Minutes for transcription.

OpenMinutes validates the file path, extension, size, and duration when duration probing is available. A successful upload prints the created Minute token and URL.

## Usage

```sh
openminutes upload FILE [flags]
```

## Arguments

| Argument | Description |
| --- | --- |
| `FILE` | Required path to one local audio or video file. Exactly one file is accepted. |

## Flags

`upload` has no command-specific flags.

Global flags such as `--config` and `--verbose` are available.

## Supported Files

Supported extensions:

```txt
.wav, .mp3, .m4a, .aac, .ogg, .wma, .amr, .avi, .wmv, .mov, .mp4, .m4v, .mpeg, .flv
```

Limits:

| Limit | Value |
| --- | --- |
| Maximum file size | 6 GiB |
| Maximum duration | 6 hours when duration probing is available |

Duration probing is implemented for `.mp4`, `.m4v`, `.m4a`, `.mov`, `.wav`, `.mp3`, and `.ogg`. For other supported extensions, duration validation is skipped when the duration is unknown.

## Examples

```sh
openminutes upload ./meeting.mp4
openminutes --verbose upload ./interview.mp3
```

## Output

Successful uploads print:

```txt
Uploaded m_abc123 https://meetings.feishu.cn/minutes/m_abc123
```

The URL is built from `base_url` and the returned object token.

## Errors And Notes

* Requires a valid config and cookie.
* `FILE` is required and must not be blank.
* Only one file path is accepted.
* The file must exist and must not be a directory.
* Unsupported file extensions fail before upload.
* Files larger than 6 GiB fail before upload.
* Files longer than 6 hours fail when duration probing is available and succeeds.

---

---
url: /cli/delete.md
---
# `openminutes delete`

## Purpose

Delete one or more Minutes from the authenticated Feishu/Lark account.

By default, each Minute is moved to trash. With `--destroy`, each Minute is permanently deleted after it is moved to trash. The command always requires `--yes`.

## Usage

```sh
openminutes delete TOKEN... [flags]
```

## Arguments

| Argument | Description |
| --- | --- |
| `TOKEN...` | One or more Minute object tokens. At least one token is required. |

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| `--yes` | `false` | Confirm deletion without prompting. Required for every delete operation. |
| `--destroy` | `false` | Permanently delete each Minute after moving it to trash. |

Global flags such as `--config` and `--verbose` are also available.

## Examples

```sh
openminutes delete m_abc123 --yes
openminutes delete m_abc123 m_def456 --yes --destroy
```

## Output

Trash deletion prints one line per token:

```txt
Moved m_abc123 to trash
```

Permanent deletion prints one line per token:

```txt
Permanently deleted m_abc123
```

## Errors And Notes

* `--yes` is required. Without it, the command fails before loading config.
* Requires a valid config and cookie after confirmation is provided.
* At least one token is required.
* Blank tokens are rejected.
* When multiple tokens are provided, OpenMinutes processes them in order and stops at the first error.
* `--destroy` is irreversible from the CLI perspective. Confirm the target tokens before running it.

---

---
url: /cli/completion.md
---
# `openminutes completion`

## Purpose

Generate shell completion scripts for OpenMinutes.

This is the parent command for the shell-specific completion generators. It does not require OpenMinutes config or a Feishu/Lark cookie.

## Usage

```sh
openminutes completion [command]
```

## Commands

| Command | Purpose |
| --- | --- |
| `openminutes completion bash` | Generate the autocompletion script for bash. |
| `openminutes completion zsh` | Generate the autocompletion script for zsh. |
| `openminutes completion fish` | Generate the autocompletion script for fish. |
| `openminutes completion powershell` | Generate the autocompletion script for PowerShell. |

## Flags

| Flag | Description |
| --- | --- |
| `-h, --help` | Show help for the completion command. |

Global flags such as `--config` and `--verbose` are available, but completion generation does not need config.

## Examples

```sh
openminutes completion --help
openminutes completion bash
openminutes completion zsh
openminutes completion fish
openminutes completion powershell
```

## Output

The shell-specific subcommands print completion scripts to stdout.

## Errors And Notes

* Redirect the generated script to the location expected by your shell, or source it in the current shell session.
* Use the shell-specific guide for installation examples.

---

---
url: /cli/completion-bash.md
---
# `openminutes completion bash`

## Purpose

Generate the bash completion script for OpenMinutes.

The generated script is written to stdout. This command does not require OpenMinutes config or a Feishu/Lark cookie.

## Usage

```sh
openminutes completion bash
```

## Arguments

This command does not accept positional arguments.

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| `--no-descriptions` | `false` | Disable completion descriptions. |
| `-h, --help` | `false` | Show help for the bash completion command. |

Global flags such as `--config` and `--verbose` are also available.

## Examples

Load completions in the current shell session:

```sh
source <(openminutes completion bash)
```

Install completions for future Linux shell sessions:

```sh
openminutes completion bash > /etc/bash_completion.d/openminutes
```

Install completions for future macOS Homebrew bash sessions:

```sh
openminutes completion bash > "$(brew --prefix)/etc/bash_completion.d/openminutes"
```

Generate without descriptions:

```sh
openminutes completion bash --no-descriptions
```

## Output

The command prints a bash completion script to stdout.

## Errors And Notes

* The generated script depends on the `bash-completion` package.
* Start a new shell after installing the script for future sessions.
* You may need elevated permissions to write to `/etc/bash_completion.d/openminutes`.

---

---
url: /cli/completion-zsh.md
---
# `openminutes completion zsh`

## Purpose

Generate the zsh completion script for OpenMinutes.

The generated script is written to stdout. This command does not require OpenMinutes config or a Feishu/Lark cookie.

## Usage

```sh
openminutes completion zsh [flags]
```

## Arguments

This command does not accept positional arguments.

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| `--no-descriptions` | `false` | Disable completion descriptions. |
| `-h, --help` | `false` | Show help for the zsh completion command. |

Global flags such as `--config` and `--verbose` are also available.

## Examples

Enable zsh completion if it is not already enabled:

```sh
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

Load completions in the current shell session:

```sh
source <(openminutes completion zsh)
```

Install completions for future Linux shell sessions:

```sh
openminutes completion zsh > "${fpath[1]}/_openminutes"
```

Install completions for future macOS Homebrew zsh sessions:

```sh
openminutes completion zsh > "$(brew --prefix)/share/zsh/site-functions/_openminutes"
```

Generate without descriptions:

```sh
openminutes completion zsh --no-descriptions
```

## Output

The command prints a zsh completion script to stdout.

## Errors And Notes

* Start a new shell after installing the script for future sessions.
* The target directory must already be in `fpath` for zsh to discover the completion file.

---

---
url: /cli/completion-fish.md
---
# `openminutes completion fish`

## Purpose

Generate the fish completion script for OpenMinutes.

The generated script is written to stdout. This command does not require OpenMinutes config or a Feishu/Lark cookie.

## Usage

```sh
openminutes completion fish [flags]
```

## Arguments

This command does not accept positional arguments.

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| `--no-descriptions` | `false` | Disable completion descriptions. |
| `-h, --help` | `false` | Show help for the fish completion command. |

Global flags such as `--config` and `--verbose` are also available.

## Examples

Load completions in the current shell session:

```fish
openminutes completion fish | source
```

Install completions for future fish sessions:

```sh
openminutes completion fish > ~/.config/fish/completions/openminutes.fish
```

Generate without descriptions:

```sh
openminutes completion fish --no-descriptions
```

## Output

The command prints a fish completion script to stdout.

## Errors And Notes

* Start a new shell after installing the script for future sessions.
* Create `~/.config/fish/completions` first if it does not exist.

---

---
url: /cli/completion-powershell.md
---
# `openminutes completion powershell`

## Purpose

Generate the PowerShell completion script for OpenMinutes.

The generated script is written to stdout. This command does not require OpenMinutes config or a Feishu/Lark cookie.

## Usage

```powershell
openminutes completion powershell [flags]
```

## Arguments

This command does not accept positional arguments.

## Flags

| Flag | Default | Description |
| --- | --- | --- |
| `--no-descriptions` | `false` | Disable completion descriptions. |
| `-h, --help` | `false` | Show help for the PowerShell completion command. |

Global flags such as `--config` and `--verbose` are also available.

## Examples

Load completions in the current shell session:

```powershell
openminutes completion powershell | Out-String | Invoke-Expression
```

Add persistent completions by appending the generated script to your PowerShell profile:

```powershell
openminutes completion powershell >> $PROFILE
```

Generate without descriptions:

```powershell
openminutes completion powershell --no-descriptions
```

## Output

The command prints a PowerShell completion script to stdout.

## Errors And Notes

* Restart PowerShell after updating your profile for future sessions.
* Confirm the profile path exists before redirecting output to `$PROFILE`.

---

---
url: /markdown-examples.md
---
# Markdown Extension Examples

This page demonstrates some of the built-in markdown extensions provided by VitePress.

## Syntax Highlighting

VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:

**Input**

````md
```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```
````

**Output**

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

## Custom Containers

**Input**

```md
::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::
```

**Output**

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

## More

Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

---

---
url: /api-examples.md
---

# Runtime API Examples

This page demonstrates usage of some of the runtime APIs provided by VitePress.

The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:

```md
<script setup>
import { useData } from 'vitepress'

const { theme, page, frontmatter } = useData()
</script>

## Results

### Theme Data
<pre>{{ theme }}</pre>

### Page Data
<pre>{{ page }}</pre>

### Page Frontmatter
<pre>{{ frontmatter }}</pre>
```

## Results

### Theme Data

### Page Data

### Page Frontmatter

## More

Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).