Configuration and Authentication¶
moi-cli supports three credential sources: personal access tokens (PAT), Astra single sign-on, and injected task runtime credentials. Before running workspace-scoped commands, configure the Product API endpoint, authentication credentials, and target workspace ID.
Authentication modes¶
Select the authentication source with the global -auth flag (auto by default):
Mode |
Credential and endpoint source |
Typical use case |
|---|---|---|
|
Reads |
Server terminals, shell scripts, CI/CD jobs, or explicit PAT sessions. |
|
Reuses the signed-in local Astra session, endpoint, and selected workspace; saved PAT settings do not trigger an automatic fallback. |
Interactive local development when the matching Astra client is installed and signed in. |
Task runtime bundle ( |
Uses |
Managed agent task sandboxes; see In-Task Knowledge Retrieval. |
Use a personal access token (PAT)¶
Create a token in the console first as described in Access credentials. Then save the endpoint, token, and default workspace:
moi-cli config set-endpoint 'https://api.moi.matrixorigin.cn/v5'
moi-cli config set-api-key '<personal-access-token>'
moi-cli -auth pat -o workspace list
moi-cli config set-workspace '<workspace-id>'
moi-cli config show
Key configuration details:
Use
https://api.moi.matrixorigin.cn/v5for the public cloud Product API, or the full Product API URL provided by your deployment administrator for private deployments.Pass the raw token value to
set-api-keywithout aBearerprefix.By default, configuration is written atomically to
~/.moi-cli.jsonwith0600permissions.config showreads the local file only and masks the token without making a network request.Because
-authdefaults toauto(Astra sign-in), always pass-auth paton business commands when authenticating with a PAT.
Use Astra single sign-on¶
When the matching Astra client is installed on your machine, sign in through your browser first and then run moi-cli:
astra login
astra auth status --json
moi-cli -auth moi -o workspace list
Astra sign-in supplies the endpoint, access token, and default workspace. Pass -workspace-id '<workspace-id>' before the command group to override the workspace for a single call. -auth moi cannot be combined with -api-key, and any explicit -endpoint flag must match the signed-in Astra environment.
Per-command overrides and config file isolation¶
Global connection flags apply only to the current process without modifying saved config files:
moi-cli -auth pat \
-endpoint 'https://api.moi.matrixorigin.cn/v5' \
-api-key '<personal-access-token>' \
-workspace-id '<workspace-id>' \
-o workspace-member current-principal
Because command-line flags can appear in process listings or CI logs, use MOI_CLI_CONFIG_FILE to isolate credentials per environment or pipeline job:
export MOI_CLI_CONFIG_FILE="/tmp/moi-prod-config.json"
moi-cli config set-endpoint 'https://api.moi.matrixorigin.cn/v5'
moi-cli config set-workspace '<workspace-id>'
MOI_CLI_CONFIG_FILE must be a clean canonical absolute path (no relative segments or redundant slashes). Once set, moi-cli reads and writes only that file and disables fallback to ~/.moi-cli.json. For temporary CI file cleanup patterns, see Non-Interactive Mode and Automation.
Configure workspace role mappings¶
When no workspace role is pinned locally, the server resolves your workspace Default Role. To pin a specific bound role for a workspace, save a workspace-to-role mapping:
# Save an active role ID (canonical positive int64) for the workspace
moi-cli config set-role '<workspace-id>' '12'
# Remove the pinned role and return to server Default Role resolution
moi-cli config unset-role '<workspace-id>'
Role mapping rules:
The role identifier must be a canonical positive decimal
int64ID; role display names are rejected.Both PAT mode and Astra sign-in share these role mappings. Each CLI process snapshots the role map once at startup, and there is no per-command
-role-idglobal flag.Local configuration only requests the role; the server still verifies direct binding and role lifecycle state and rejects invalid roles without falling back to another role.
Warning
If any persisted role mapping in your config file is malformed (for example, a role name or empty string), moi-cli aborts before sending any authentication or business request with No request was sent.. Run moi-cli config show to inspect saved mappings, then fix or remove the entry with moi-cli config set-role or moi-cli config unset-role.
To inspect workspace roles and bindings, see Workspaces and Permissions.
Request timeouts and offline commands¶
Standard commands use a default 30s HTTP deadline. For large payloads or slower synchronous endpoints, pass a positive duration to -request-timeout before the command group (covering both request transmission and response body reads):
moi-cli -auth pat -request-timeout 2m -o catalog tree
If a write command times out, the server may still complete the operation. Inspect the target resource or operation receipt before retrying non-idempotent writes.
The following commands run completely offline without credentials or network access:
Version and help:
moi-cli -version,moi-cli --help,moi-cli <command-group> <subcommand> --helpLocal config management:
moi-cli config ...JSON input schemas and bundled skill docs:
moi-cli schema ...,moi-cli skill ...(see Command Reference)Offline agent package utilities:
moi-cli agent init,build,verify,unpack