Troubleshooting

Practical fixes for the issues you’re most likely to hit.

Authentication failures

If a command returns an authentication error, confirm which identity (if any) the CLI is resolving:

suya auth whoami     # calls the API and prints the resolved identity
suya auth status     # local auth status, no server call

For agents and CI, make sure SUBAYA_API_KEY is exported in the shell that runs suya:

echo "${SUBAYA_API_KEY:?SUBAYA_API_KEY is not set}"

Remember the credential precedence: the --token flag wins, then SUBAYA_API_KEY, then the locally stored OAuth token. If you logged in long ago, a fresh suya auth login re-establishes the local token. See Authentication & API keys.

Commands hit the wrong host

Every command talks to https://subaya-dev.com by default. If requests are failing or landing somewhere unexpected, check that you haven’t passed a stray --host:

suya auth whoami --host https://subaya-dev.com

Only override --host when you intend to target a non-default API endpoint.

suya sim run can’t find the testbench

The --tb path is interpreted within the --source tree, not relative to your shell’s working directory. If the run reports a missing testbench, verify the path resolves inside the source directory you’re uploading:

suya sim run --source . --tb tb/top_tb.sv --top top --tool ryusim

Two things to check:

• The --tb path exists under the --source directory.
• The --source tree is 4 MB or smaller — trim build artifacts and large binary files before submitting.

See CLI: sim for the full simulation surface.

suya repo connect / repo create fails

Both repo commands require the GitHub App installation id via --installation:

suya repo connect --installation <id> --owner <o> --repo <r>
suya repo create  --installation <id> --name <n>

If you don’t have an installation id yet, install the GitHub App first — see Connect a GitHub repo. Confirm the current connection state with:

suya repo status

Stale CLI

If a command or flag is missing, or behavior doesn’t match these docs, your CLI may be out of date. Check and upgrade:

suya version            # show version metadata
suya update --check     # report whether a newer release exists
suya update             # upgrade to the latest release

Still stuck?

• Re-run with -v/--verbose for extra diagnostics, or --json for machine-readable output.
• Check service health on the Status page.
• Browse the full command surface in the CLI reference.