Skip to main content

CLI troubleshooting and recovery

Start with nameslink --version to identify the actual binary. For login or connectivity diagnostics, run nameslink doctor once. Avoid starting multiple login or diagnostic processes in parallel.

Open a new terminal, check that node --version is at least 20, and retry the public installation command. If an old internal package was installed, check which entry point runs: use command -v nameslink on macOS / Linux or Get-Command nameslink in PowerShell.

Public installation needs neither an internal npm registry nor a company npm account. Do not replace the global registry for unrelated packages.

The browser is signed in, but the CLI is not​

Browser sessions and CLI credentials are separate. Run nameslink login, authorize in the browser, return to the original terminal process, and run nameslink whoami.

Check the API address. Credentials are bound to the endpoint used at login. Sign in again for a changed endpoint rather than reusing another environment's credentials. The public default is https://www.nameslink.com/api.

nameslink login --no-browser provides a manual authorization entry for remote terminals, but the CLI's local callback must still be reachable. It does not add cross-device login without a callback. Keep the authorization link private.

macOS asks for a Keychain password​

Keep the current CLI process waiting, inspect the system prompt, and authorize through that prompt. Do not enter the password in an AI chat or shell command. If the process has timed out, dismiss stale prompts and retry once. Repeated processes can create repeated prompts.

On Windows or Linux, follow doctor when credential storage is unavailable. Do not guess by deleting credential files or disabling protections.

Publication asks for MFA, or a code expires​

MFA is a normal step for protected changes. Interactive users should follow the current terminal process. AI / JSON workflows should follow the returned challenge, send-code, and continuation commands for the same challenge.

Do not put codes in command arguments, environment variables, shell history, or chats. Agents must use the official Skill's safe input method. For a missing or expired code, follow that challenge's resend or verification steps instead of repeatedly starting publication.

Upload or publication was interrupted​

  1. Keep the original output: site ID, operation ID, original idempotencyKey, and recovery commands such as resumeCommand.

  2. Follow the returned command to inspect the original operation, or query the same site:

    nameslink site hosted status <site-id> --watch --json
    nameslink site hosted operation <site-id> <operation-id> --json

  3. Resume only as instructed, with the same operation, files, and destination. An unknown result is not a reason to change the key, reupload, or republish.

  4. --watch has a waiting limit. Reaching that limit does not mean the business operation failed. Query the original status again later.

If files changed, first reconcile the original operation, then use the normal new-version workflow. Do not treat changed files as the same retry.

If the command stopped before returning a site ID, run nameslink site hosted list --json to check existing sites. If you still cannot identify the result, keep the operation time and redacted output and contact support before creating another site.

A command exists but the service is unavailable​

nameslink capabilities --json
nameslink site hosted capability --json

Use the current server's availability, reason, and next action. Do not bypass a restriction through retired APIs, other hosting products, or another account. For invalid static files, see file and preview troubleshooting.

Contact support​

Use the contact page or ticket@nameslink.com. Provide the CLI version, operating system, API address, exact error, time, and masked operation ID. Share account or domain details through a private ticket rather than public diagnostic output. Never include passwords, AK/SK, OAuth authorization URLs, MFA codes, or recovery tokens.