Start here

Setup & authentication

Onboarding starts in the dashboard, not the terminal. You sign in with GitHub, complete a short setup wizard, then mint an API key — and only then does the CLI come in, using that key. This page walks the whole path and the access Moa needs.

Note.The dashboard is the front door. The moa CLI is a second interface you connect after onboarding — moa login only stores an API key you create in the dashboard; it does not onboard you.

Onboard in the dashboard#

Open app.fnmoa.com and sign in with GitHub. A default org is created for you, and a setup wizard walks you through connecting everything. The org owner completes the full wizard; invited members only connect their own GitHub identity — the owner sets the workspace, app, repos, and Claude for the org.

The setup steps (owner)

Workspace

Point your org at its Moa workspace — the server that actually runs the workflows.

GitHub identity

Registers you in the org's workspace so Moa can act as your GitHub identity. It reuses your sign-in — nothing extra to paste. Members stop here.

GitHub App

Install the Moa GitHub App and pick the account and repositories it may access. This is deny-all: nothing outside the installation is ever touched. The step completes itself when you return from GitHub.

Allowed repos

Choose which installed repos Moa may run workflows on — everything else is denied. You can change this anytime from the Repos view.

Claude

Connect the workspace's shared Claude login, which drives the agent. Manage which key your runs bill against under Settings → Billing (bring your own key, or a metered Moa key).

Note.Workspace, App, allowed repos, and Claude are owner-managed. If you're a member and hit “Only the workspace owner can change global connectors,” that's expected — ask your owner to set them.

Connect the CLI#

Once onboarding is done, the CLI authenticates with an API key you create in the dashboard — it is not a separate login.

Create a key

In the dashboard, open Keys → New key, name it, and choose its scopes (task — the HTTP task API — is the one the CLI needs; mcp and acp are for those endpoints). The key is shown once — copy it immediately.

Install the CLI

bash

npm i -g @fnmoa/cli

Store the key

Run moa login — it prompts for your workspace API URL and the key, and saves them to a local profile.

bash

moa login

Prefer non-interactive (CI, scripts)? Set them directly, or use environment variables:

bash

moa config set url https://api.fnmoa.com
moa config set key moa_xxx
# or, per-shell:
export MOA_API_URL=https://api.fnmoa.com
export MOA_API_KEY=moa_xxx

Note.auto-bootstrap is unavailable on first run is expected on the hosted product — it means the workspace is enrolled to a control-plane, so there's no key to bootstrap. Create one in the dashboard and run moa login. (Auto-bootstrap only applies to a standalone, single-operator workspace.)

What Moa can do, and why#

Through the GitHub App installation — scoped to your allowed repos — Moa requests only the access its workflows need. At the capability level:

Code (read & write)

Read the repo to reason about a fix; push changes to a branch. Moa never force-pushes or writes to your default branch directly.

Pull requests

Open PRs, post review comments, and merge when checks are green and the review approves.

Issues

Read issues to triage and solve; apply labels and leave comments.

Checks / CI

Read failing checks and their logs to fix CI and gate merges on green.

Webhooks

Receive issue and PR events so workflows can trigger automatically.

Tip.Deny-all means Moa only ever acts on the repos you allow. Change the selection — or revoke the app entirely — from GitHub or the Repos view at any time; it takes effect immediately.

Where credentials live#

CLI key — stored locally in your Moa CLI config after moa login. Use profiles to keep more than one. Revoke it from the dashboard Keys page.
Claude & GitHub connections — stored server-side in your workspace, encrypted at rest, never in a file or env you manage. Each org is isolated to its own data.

Verify your setup#

You're ready when all three are green:

bash

moa status

operator   you@org · workspace api.fnmoa.com
claude     connected
github     connected · 4 repos

Stuck?.If moa login can't reach the workspace, or a connector reads not connected, see Troubleshooting.