Troubleshooting

Most CLI problems are one of six things. They are quick to tell apart, and the first two account for most of them.

not signed in

No credentials on this machine, or they were revoked.

omazy auth login --email you@example.com

Tokens are scoped to one machine, so signing in on your laptop does nothing for your CI runner. That is deliberate: it means losing the laptop does not take CI down with it. See Authentication.

UNAUTHORIZED: missing or malformed authorization header

Different from the one above. Here a token was sent and rejected, usually because it expired or was revoked from another machine.

Sign in again. If it recurs immediately, check that you are on the profile you think you are: omazy config profile.

no workspace selected or no app selected

The command needs a scope and could not find one.

omazy workspace use acme
omazy config set workspace acme

Or pass it explicitly for one command with --workspace and --app. Explicit beats ambient whenever the command touches production.

A command returns 403

You are signed in, and the answer is still no. This is a permission problem rather than a credential problem, so signing in again will not fix it.

Ask an owner to widen your role. The full list of what each role can do is in Roles and permissions, and the error codes are in Error codes.

could not reach https://cli.omazy.ai during install

The installer proxies release assets through cli.omazy.ai. If that host is unreachable from your network, the usual cause is a corporate proxy or a DNS policy rather than an outage.

With repository access, OMAZY_TOKEN bypasses the proxy and pulls straight from GitHub.

Everything is slow

Check where the time is going before assuming the platform is at fault:

omazy --debug agent show

--debug prints the requests and responses. It usually reveals one of three things: you are pointed at a different app than you thought, a single call is slow rather than all of them, or you are being rate limited and retrying.

Getting help

Capture these three things and a support conversation goes from days to minutes:

• omazy version
• the exact command, with --debug
• the error code, not just the message

The code is the stable part. Messages get reworded; codes do not.

Not available yet

Two things people look for and will not find:

	Status
A terminal dashboard	Planned for 0.3
Running the CLI as an MCP server	Planned for 0.2

omazy mcp-server does exist and is a different thing: it browses the public MCP server catalogue. It does not turn the CLI into a server.