Skip to main content
Start with: 
almanac doctor
almanac whoami

​
almanac is not found

Open a new shell after installation. If needed, reinstall with uv tool install the-almanac, then run almanac --version. See Install the CLI.

​
The CLI asks you to sign in

Run almanac login. For automation, confirm ALMANAC_TOKEN contains the actual waka_... secret rather than an API key ID or obfuscated value. Secrets are shown only once.

​
No wiki is selected

Run almanac whoami, then either link the project or pass an explicit handle: 
almanac link acme/company-handbook
almanac search "onboarding" --wiki acme/company-handbook
Review the wiki context order if the wrong wiki wins.

​
Upload created no job

If the output says already in library, every file was a duplicate and no new job exists. Do not wait on last; it still refers to an older job. See Upload sources.

​
A job failed or stopped progressing

almanac jobs show job_123
almanac jobs events job_123
Keep the job ID and final request_id or error when reporting the problem. See Follow a job for the available views.

​
Search returns no results

Queries need at least two letters or numbers. Confirm the job succeeded, verify the selected wiki, then browse almanac pages list and almanac sources tree to separate a page-generation problem from a missing-source problem.

​
MCP will not connect

The intended public MCP hostname is currently called out as unverified on the MCP setup page. Use the CLI, SDK, or REST API until that warning is removed; do not substitute an internal service origin.