andocs

ANDocs — Agent Native Documentation. Modern documentation tool for AI agent workflows with live Mermaid diagrams and PDF generation.

Requires Bun runtime.

Quick Start

# Start server (auto-detects markdown files)
bunx andocs

# Use specific documents folder
bunx andocs --path ./my-docs

# Start a new prototype from an idea
bunx andocs hello --prompt "Build a CRM for managing clients" --path ./new-project

# Limit nested folder scanning depth
bunx andocs --path ./my-docs --scan-depth 2

# Start on custom port
bunx andocs --port 8080

# Generate PDFs for all documents
bunx andocs pdf

# Generate PDF for specific document
bunx andocs pdf --file docs/guide.md

Agent onboarding

Run this command from the project folder. A fresh agent can follow its text output without an installed Andocs skill.

bunx andocs agent
bunx andocs agent --json --offline
bunx andocs agent --path ./project --docs-path docs

The command reports folder state, Git state, both project skill copies, CLI version, OpenDesign readiness, its selected coding agent, and the local data host. Login reports "not available yet".

In a safe project folder, the command installs missing skill files without replacing existing files. A wrong folder needs a folder selection first. An empty project asks one question about the user's idea. A documentation project asks about the user's task on the first visit.

After the agent establishes the user's intent, --acknowledge-project saves a marker in Andocs local state outside the project. An empty folder still asks about the intended task on later runs. The command never downloads or starts OpenDesign. --offline skips the npm version request.

--json writes one result with schemaVersion: 1. Exit 0 means the check completed, including a question for the user. Exit 2 means the folder or configuration cannot be used. Exit 1 means the command failed.

Commands

• serve (default) — Start local web server for browsing documentation
• hello --prompt <text> — Start one OpenDesign run from an idea
• publish — Publish a checked snapshot and open its synced member URL
• pdf — Generate PDF from one file (--file) or all documents

Publish documentation

Run andocs publish from the project folder. Sign in when the command asks. Select an existing linked project, a new project in an existing organization, or a new personal organization and repository.

andocs publish --dry-run
andocs publish
andocs publish --organization <id> --project <id> --repository <project-repository-id>
andocs publish --organization <id> --project-name "Product docs" --owner github-organization --name product-docs
andocs publish --organization-name "My docs" --project-name "My project" --owner github-login --name my-docs

The command asks a separate y/n question before creating an organization, project, or private GitHub repository. Only y approves a creation. There is no blanket --yes option. Publication is free.

--dry-run lists the files to upload and omitted files with their reasons. The upload includes the configured documents folder, .andocs/, and shared instructions, agents, commands, skills, and references under .agents/ and .claude/. Application code outside these folders stays local. Secret files, detected credentials, agent sessions, generated helpers, and file links that leave the published folders or have no usable destination are omitted. Local prototype datasets do not move with the publication.

--documents-root <folder> must match the project's configured docs path. Repository-root documentation is refused. Use or create a docs/ folder and select that folder in the project repository settings.

After the commit, the CLI explicitly starts the project sync. It waits up to two minutes for the server to confirm that the uploaded commit has synced. On success, it prints and opens the server member URL of the document with a canonical prototype block. Without a prototype, it opens the main Markdown document. Members need their usual project access.

If the command needs GitHub authorization or installation access, follow the printed browser URL. Resume the same operation after that step.

andocs publish --operation <operation-id> --root <project-folder>
andocs publish status --operation <operation-id>

If the branch changed, plan a new operation with andocs publish --operation <operation-id> --new-operation. The command reuses the linked project and repository. It does not recreate them.

A sync timeout prints the operation ID and the status command. The status command reads the stored state and does not start another sync.

For an agent, use --json with explicit target flags. A needs-confirmation result contains one question and one operation-bound approval command per creation. Obtain the user's answer before running each approval command. Then resume the operation.

andocs publish --approve-creation <operation-id>:project:<digest>
andocs publish --operation <operation-id> --root <project-folder> --json

Each publish command accepts --url <origin>. Login credentials and durable local receipts stay separate for each origin.

Options

Andocs account commands

andocs login prints a device code and opens the Andocs approval page. Sign in and approve the CLI there. Use --no-open to open the printed URL yourself.

| Command | Result | | --- | --- | | andocs login | Save an approved CLI grant. | | andocs logout | Revoke this CLI grant and delete local credentials. | | andocs whoami | Show the current account, origin, scopes, expiry, and credential store. | | andocs organizations list | List your organizations and project-creation capability. | | andocs projects list --organization <id> | List accessible projects, capabilities, and member URLs. | | andocs projects repositories --project <id> | List linked repository IDs, names, and docs paths for publish. | | andocs projects url --project <id> | Show the project member URL. | | andocs sync status --project <id> | Read stored sync status and commit. This command never starts sync. |

Each account command accepts --json and --url <origin>. The origin defaults to ANDOCS_URL, then https://andocs.blogic.cz. Use an HTTPS origin, or an explicit loopback origin such as http://localhost:3000. Credentials stay separate for each origin.

Credentials use macOS Keychain, Windows Credential Manager, or Linux Secret Service. When the keychain is unavailable, login reports the private file fallback. The fallback lives in the platform's Andocs state directory. Its auth directory has mode 0700 and its files have mode 0600. Windows requires a verified user-only ACL. Tokens never appear in command output or process arguments.

The CLI serializes refresh across processes and replaces each token pair atomically. Uncertain rotation recovery requires a new login. In JSON mode, API commands return reauthentication-needed and nextCommand without waiting for input. Device-login progress goes to stderr. Stdout contains one result with schemaVersion: 1.

Logout removes local credentials even when remote revocation fails. It reports that failure and exits with code 1. Other request failures also exit with code 1.

| Option | Description | Default | | --- | --- | --- | | --path <PATH> | Path to documents folder | Auto-detect | | --scan-depth <N> | Max nested folder depth to scan for markdown files (0 = docs root only) | 10 | | --port <PORT> | Server port | 3030 | | --host <HOST> | Server host | 127.0.0.1 | | --no-open | Don't auto-open browser | false |

Environment Variables

| Variable | Description | | ------------- | ------------------------ | | ANDOCS_PATH | Default documents folder | | ANDOCS_PORT | Default server port | | ANDOCS_HOST | Default server host |

Without --path or ANDOCS_PATH, Andocs selects docs/ when all discovered Markdown is inside it, unless the selected local data directory contains a saved project-root preview origin or dataset catalog, including a legacy catalog. Saved root state keeps the project root even with no Markdown files. A stored prototype receipt keeps its documents root, and agent follows the same selection rule.

Development

# Start dev server
bun run --filter "andocs" dev

# Build standalone binary + web assets
bun run --filter "andocs" build

# Build web assets only
bun run --filter "andocs" build:web

Build Outputs

• dist/andocs — Compiled standalone binary
• dist/web/ — Built React web app served by CLI server

Storage directory

ANDOCS_STORAGE_DIRECTORY overrides the CLI user data directory on all platforms. It contains project skill receipts, credentials, and other CLI state. Set an absolute path for an isolated CLI instance. Relative paths, including ~/..., are rejected. Child processes inherit the setting. When the variable is empty or unset, the CLI uses the platform default directory.

The managed OpenDesign runtime folder is a shared pinned cache and is not moved by ANDOCS_STORAGE_DIRECTORY. Tests isolate it through HOME.

License

Copyright (c) 2025-present Blogic s.r.o. All rights reserved. See LICENSE.