Atelier docs

Troubleshooting

Common issues and safe recovery steps for Atelier.

Node.js is too old

If atl will not start after install, check that your shell is using Node.js 22.12 or newer.

node --version
atl --version

Unexpected API URL

Use JSON diagnostics before logging in. If the API URL is not https://atelier.mananjoshi.me/api, check ATELIER_API_URL in your shell or local project environment.

atl doctor --json
atl whoami --json

An agent or script hit an interactive prompt

GitHub login, vault passphrase entry, and destructive confirmations are intentionally interactive. Hand those steps to the user, then rerun read-only or preview commands with JSON output.

atl guide --json
atl profile switch personal --preview --json

No inventory found

Commands such as atl list and atl inspect need a local inventory from a previous scan.

atl scan

Not logged in

atl login
atl whoami --json

Unexpected account state

If atl doctor shows an unexpected session or account state, logout and login again.

atl doctor
atl logout
atl login

Vault is locked

Atelier asks for your vault passphrase when a save or apply operation needs decrypted key material.

atl vault status
atl vault unlock

Apply is blocked

A blocked apply means the target file exists and differs from the saved version. Preview the diff, then apply with a backup if the saved version should replace the local file.

atl apply zed.settings --preview
atl apply zed.settings --backup

Profile switch is blocked

Profile switch blocks if any saved config would replace a differing local file. Use preview to inspect the plan.

atl profile switch personal --preview
atl profile switch personal --backup

A saved config is missing

Check the active profile first. Saved configs are scoped to profiles.

atl profile current
atl profile list
atl saved list

A file is blocked during save

Atelier blocks files that look private, generated, too large, or unsafe to save. Inspect the item to see the reason.

atl inspect <id-or-path>