AskVoro
AskVoro documentation

Docs as code

The askvoro CLI

Keep your help center as Markdown in your own repository and push it to AskVoro. Documentation gets reviewed in pull requests and ships with the change that made it necessary, instead of being a dashboard task someone remembers on Friday.

The docs you're reading now are written and published this way.

Install#

The CLI package is currently private to the AskVoro monorepo and is not available from the npm registry yet. Contributors run the source entry point:

bash
bun run askvoro -- help

To expose a local askvoro command while developing it, build and link the workspace package:

bash
bun run --cwd packages/askvoro-cli build
cd packages/askvoro-cli
bun link

Start a project#

In the folder where your docs should live:

bash
askvoro init --workspace YOUR_WORKSPACE_ID --knowledge-base help --faqs

That writes a .askvoro file. Add --faqs to configure Markdown below faqs/ as FAQs; create the directory when you add the first FAQ.

json
{
  "workspaceId": "YOUR_WORKSPACE_ID",
  "knowledgeBase": "help",
  "visibility": "hidden",
  "sourceId": "src_generated_by_init",
  "origin": "https://askvoro.com",
  "faqs": {
    "directory": "faqs"
  }
}

Add "publish": false to push everything as drafts — useful while you're migrating an existing help center and don't want it live mid-import.

init starts with hidden knowledge-base visibility. Change it to public or internal before the first push when that is the intended initial access.

visibility controls only the initial knowledge-base visibility: hidden, internal, or public. Once the base exists, visibility changes made in the dashboard stay in the dashboard and are not overwritten by later pushes.

The source id is generated once. Keep it in version control: it is how AskVoro continues to identify this repository after someone renames the knowledge-base slug in the dashboard.

Starting from the dashboard#

If the knowledge base already exists, open it in the dashboard and choose the CLI tab. Register a repository source there, adjust the origin, draft/publish, and FAQ options, then download the generated .askvoro file. A dashboard-registered source can be pulled immediately; it does not need an initial push just to create the source link.

Pull remains source-scoped. It downloads files previously synced by that source; articles created only in the dashboard stay in the dashboard.

Log in#

bash
askvoro login

This opens your browser, you confirm as a signed-in workspace admin, and a docs-only API key is written to ~/.config/askvoro/credentials.json with user-only permissions. The key can read and write articles and FAQs, and nothing else.

The login is deliberately browser-only — the authorising request is rejected unless it comes from a real browser on the site itself, so it can't be driven by a script. Credentials are stored per origin and workspace, so switching either one in .askvoro means logging in again.

--no-open prints the URL instead of launching a browser. The login expires after three minutes if you don't confirm.

Continuous integration#

Don't use the browser flow in CI. Create an API key in the dashboard and pass it as an environment variable:

bash
ASKVORO_TOKEN=sk_... askvoro push

ASKVORO_TOKEN takes precedence over stored credentials. Pull and push do not accept a --token flag. askvoro login --token sk_... is only for validating and storing a dashboard-created key on a machine with a credentials file.

Then#