Connect to a Mockarty Server

This page explains how the Mockarty CLI chooses which server to talk to, and how to override that choice for local development, self-hosted deployments, or air-gapped installs.

TL;DR. Out of the box, mockarty-cli points at a local Mockarty instance (http://localhost:5770). To use a different server, either pass --server <url> on each command, export MOCKARTY_SERVER=<url>, or persist the URL with mockarty-cli config set-context <name> --server <url>.

Server URL Resolution

Every CLI command resolves its target server by walking a four-step precedence chain. The first non-empty value wins.

The legacy MOCKARTY_SERVER_URL environment variable is still honoured as an alias for MOCKARTY_SERVER so existing CI scripts keep working; if both are set, MOCKARTY_SERVER takes precedence.

Common Scenarios

1. Default install — local instance

After installing the CLI, the very first command targets a local Mockarty instance:

mockarty-cli auth login
# Server: http://localhost:5770
# Contacting Mockarty server for authentication methods…

The CLI prints the resolved server before starting the OAuth flow so you can verify the destination at a glance. If the printed URL is wrong, abort with Ctrl-C and re-run with --server <your-server-url> (or point at your self-hosted instance — see below).

2. Local development against a running Mockarty instance

Most developers run a local admin node on http://localhost:5770. The cleanest way is a one-line env override per shell session:

export MOCKARTY_SERVER=http://localhost:5770
mockarty-cli auth login
# Server: http://localhost:5770

Or per-command, without changing the shell:

mockarty-cli --server http://localhost:5770 auth login

3. Self-hosted corporate Mockarty

A long-lived persistent default goes into ~/.mockarty/config.json and survives across shells, containers, and reboots:

mockarty-cli config set-context corp --server https://mockarty.internal.corp
mockarty-cli auth login

After this any subsequent mockarty-cli mock list / mockarty-cli run / mockarty-cli ... command targets the corporate server automatically — no flag, no env var.

4. Air-gapped / multiple servers in one shell

For users that frequently switch between two or three servers, prefer the env-var path so each new shell starts with a known target:

# ~/.bashrc / ~/.zshrc
export MOCKARTY_SERVER=https://mockarty.internal.corp

# Per-job override for one CI step only:
MOCKARTY_SERVER=http://localhost:5770 mockarty-cli mock list

Verifying the Active Server

Use mockarty-cli config view to inspect the merged configuration the CLI will actually use:

mockarty-cli config view

The server_url value reflects the full precedence chain — flags layered over env layered over file layered over the compiled-in default. If something is unexpected, this output is the single source of truth.

Why a Local Default

A fresh install with no flag, no env, no file still has a useful, well-known target: a local Mockarty instance on http://localhost:5770. New users can start a local server and run mockarty-cli auth login immediately without having to know any URL first. Existing users with a corporate config feel no change — their personal override (a self-hosted server URL) sits above the default in the precedence chain.

The compiled-in default can also be overridden at build time, so a custom distribution can ship with a different well-known target; the precedence chain above still applies on top of whatever default the binary was built with.

Related Docs

• CLI User Guide — full command reference
• Quick Start — five-minute onboarding
• CLI in a Container — Docker / Kubernetes patterns
• Tips & Useful Features — why we use localhost:5770 placeholders elsewhere