The Connector needs two pieces of information before it can do anything useful: which Kuali instance to talk to and a Kuali API key that identifies you. You only configure this once per machine.
Your Kuali instance URL — something like https://yourschool.kualihub.com.
A Kuali API key. Create one in the Kuali web UI under Settings → API Keys. The key inherits the permissions of the user that created it, so create it as the user whose access you want the Connector (and, by extension, your AI assistant) to have.
The Connector never handles your Kuali password. An API key is a signed token you can revoke any time from the same screen you created it on.
The API key the Connector uses carries exactly the permissions of the user that created it — nothing more. If your user account can't see an app, a document, or a user in the Kuali web UI, the Connector can't see it either, and neither can your AI assistant. To narrow the assistant's reach, issue an API key for a Kuali user with tighter permissions rather than your admin account.
For most people the fastest way to get connected is one guided command:
$
kuali setup
Kuali hostname: yourschool.kualihub.com
API key: ••••••••••••••••
Profile "yourschool" saved · API key validated ✓
You'll be asked for two things — your Kuali hostname (e.g. yourschool.kualihub.com) and your API key (input is hidden).
setup derives the API URL (https:// + hostname) and a profile name (the subdomain — yourschool here) from that single hostname, validates the key against your instance, and saves the result. The first profile you create is also set as the default.
You can also pass everything as flags for non-interactive use:
$
kuali setup --hostname yourschool.kualihub.com --api-key YOUR_KEY
Useful flags: --profile myname to override the auto-derived profile name, --force to overwrite an existing profile, --default=false to leave the default-profile pointer alone.
Skip ahead to Verify once setup reports success.
The original two-step flow still works and is the right path when you need finer control (for example, an http:// URL for local dev) or when you want to tweak settings on an existing profile without re-entering everything.
$
kuali config set api_url https://yourschool.kualihub.com --profile yourschool
The --profile flag is a label you pick. If you only ever talk to one Kuali instance, omit it — the Connector will use the default profile:
$
kuali config set api_url https://yourschool.kualihub.com
The URL is written to ~/.kuali/config.yaml.
$
kuali auth login --profile yourschool
You'll be prompted for the API key. The key is written to your OS keychain (macOS Keychain, Windows Credential Manager, or libsecret on Linux) — it never lands in a plaintext file you might accidentally commit or email.
$
kuali doctor --profile yourschool
✓ config ✓ URL ✓ key stored ✓ reachable ✓ accepted
doctor runs six checks: config file is readable, API URL is configured, tenant is set (warning only), API key is stored, the instance is reachable over HTTP, and the key is accepted by the GraphQL API. Any failure gives you a specific remediation step.
A quick smoke test:
$
kuali apps list --profile yourschool
You should see your institution's apps.
Most teams have at least a sandbox and a production instance. Give each one its own profile — the easiest way is to run kuali setup once per environment:
$
kuali setup --hostname sandbox.kualihub.com --api-key $SANDBOX_KEY
$
kuali setup --hostname prod.kualihub.com --api-key $PROD_KEY
Each call derives its own profile name from the subdomain (sandbox, prod). Or, using the manual flow:
$
kuali config set api_url https://sandbox.kualihub.com --profile sandbox
$
kuali auth login --profile sandbox
$
kuali config set api_url https://prod.kualihub.com --profile prod
$
kuali auth login --profile prod
Then pick per command:
$
kuali apps list --profile sandbox
$
kuali apps list --profile prod
Set a default profile with the KUALI_PROFILE environment variable or:
$
kuali config set default_profile prod
In automated environments you may not want to set up the keychain. The Connector reads API keys from profile-specific environment variables:
$
export KUALI_PROD_API_KEY=<key>
$
export KUALI_SANDBOX_API_KEY=<key>
$
kuali apps list --profile prod # uses KUALI_PROD_API_KEY
$
kuali apps list --profile sandbox # uses KUALI_SANDBOX_API_KEY
A plain KUALI_API_KEY still works and applies to all profiles, but it overrides the per-profile values — so avoid it when you have more than one environment.
$
kuali auth logout --profile yourschool
Removes the stored key for that profile. The URL and other settings stay in the config file — run the command again with a new key whenever you're ready.
If you're talking to a local dev instance with a self-signed cert:
$
kuali config set insecure true --profile local
Or pass -k on any command. Don't turn this on for production.
Last updated: September 21, 2026
ON THIS PAGE
The API key carries exactly the permissions of the user that created it. To narrow the assistant's reach, issue a key for a tighter-permission user.
Read-only mode ->
Ready-to-use prompts for curriculum, research, build apps, imports, workflow analysis, and reporting.
Browse prompts →
Tips for Claude Desktop, Claude Code, Codex, Gemini, Copilot, and VS Code.
AI assistants →
Skip the chat — every capability is also a plain kuali command, ready for scripts and CI.
Command reference →