Skip to content

Setup Guide

Jump to bottom
Neil Martin edited this page Jul 31, 2026 · 24 revisions

Setup Guide

Get from zero to your first command.

Installation

Homebrew (macOS/Linux)

brew install Jamf-Concepts/tap/jamf-cli

Binary releases

Download pre-built binaries from GitHub Releases. Archives are available for macOS, Linux, and Windows on both amd64 and arm64.

From source

go install github.com/Jamf-Concepts/jamf-cli/cmd/jamf-cli@latest

Staying current

Releases land roughly weekly, and a stale binary is the usual cause of "that command doesn't exist" against endpoints a newer build already generates. Since v1.26.0 an interactive release build checks once a day whether a newer version exists and prints a one-line hint naming the upgrade command for your install channel:

hint: new jamf-cli release: v1.25.2 → v1.26.0 (brew upgrade jamf-cli)
      https://github.com/Jamf-Concepts/jamf-cli/releases/tag/v1.26.0

It never runs in CI, when output is piped, or under --quiet / --no-hints, and the CLI never updates itself. To silence it, see Configuration & Profiles#Release Update Notice (v1.26.0+).

A go install build now reports its real module version rather than dev, so bug reports from that channel are traceable and the notice works there too.

Jamf Pro Quick Start — Platform Gateway (Recommended)

For Jamf Cloud instances, the platform gateway is the recommended setup path. A single profile routes all Pro API traffic through the Jamf Platform Gateway and unlocks additional Platform API commands — blueprints, compliance benchmarks, device groups, and DDM reports.

Note: The Platform API is currently in beta. See the Platform API documentation for details.

Step 1 — Create API client credentials in the Jamf Account portal. See the Getting started with Platform API guide for instructions.

Step 2 — Run the setup wizard:

jamf-cli platform setup

You'll be guided through:

  1. Profile name (default: platform)
  2. Region — US, EU, APAC, or a custom gateway URL
  3. Tenant ID — from the Jamf Account portal
  4. Client ID and Client Secret — hidden input, stored in the system keychain

The wizard validates credentials against the gateway before saving. Once complete:

# Pro API commands work through the gateway
jamf-cli pro computers list
jamf-cli pro computers get --name "Neil's MacBook"

# Platform API commands are now available
jamf-cli pro blueprints list
jamf-cli pro compliance-benchmarks list
jamf-cli pro ddm-reports device declarations <device-id> --filter 'active==true'   # --filter is required

Platform setup flags

Flag Description
--profile-name Profile name (default: platform)

Credentials (client ID and client secret) are always collected via interactive prompts with hidden input. platform setup requires interactive input and cannot be fully automated. For CI/CD environments, use environment variables directly (see Configuration & Profiles#Environment Variables).

Jamf Pro Quick Start — Direct Instance

For on-premises instances, or Jamf Cloud instances where platform gateway credentials are not available, use pro setup. This uses your Jamf Pro admin credentials to create a dedicated API integration with OAuth2 client credentials directly on the instance. Your admin password is not stored.

jamf-cli pro setup --url https://jamf.company.com

You'll be prompted for your admin username, password (hidden input), and a privilege scope. That's it — the CLI handles creating the API role, integration, and credentials automatically. Once complete, you can start running commands immediately:

jamf-cli pro computers list

Note: Direct instance profiles do not have access to Platform API commands (blueprints, compliance-benchmarks, platform-devices, platform-device-groups, ddm-reports). To use those, set up a platform gateway profile.

Scope options

Scope What it allows
read-only Read and view access to all resources
standard (default) All operations except delete, flush, dismiss, and remote wipe/lock commands
full-admin All privileges

SSO or no local accounts? If your Jamf Pro instance uses SSO and local admin accounts are disabled, pro setup won't work — it requires a local username and password to bootstrap credentials. See SSO / No local accounts below for the manual path.

Jamf Protect Quick Start

Jamf Protect uses OAuth2 client credentials that you create in the Jamf Protect console. Navigate to Settings > API Clients in your Protect tenant to generate a client ID and secret before running this command.

jamf-cli protect setup --url https://tenant.protect.jamfcloud.com

You'll be prompted for the client ID and client secret (hidden input). Secrets are stored in the system keychain automatically. Once complete, run commands immediately:

jamf-cli protect overview
jamf-cli protect plans list

Setup flags

Flag Description
--url Jamf Protect URL (e.g., https://tenant.protect.jamfcloud.com)
--profile-name Profile name (default: protect)

Credentials (client ID and client secret) are always collected via interactive prompts with hidden input. This prevents accidental exposure in shell history and process listings.

Note: protect setup requires interactive input and cannot be fully automated. For CI/CD environments, use environment variables directly (see below) or create a config profile with env: / file: secret references.

Environment variable authentication

For quick ad-hoc use or CI pipelines, skip profiles entirely:

export JAMFPROTECT_URL="https://tenant.protect.jamfcloud.com"
export JAMFPROTECT_CLIENT_ID="your-client-id"
export JAMFPROTECT_CLIENT_SECRET="your-client-secret"

jamf-cli protect plans list

Note: Protect-specific env vars (JAMFPROTECT_*) take priority. The generic JAMF_URL, JAMF_CLIENT_ID, and JAMF_CLIENT_SECRET are also checked as fallbacks.

Jamf School Quick Start

Jamf School uses API key authentication (network ID + API key). Generate these in the Jamf School console: Organization > Settings > API for the API key, and find the Network ID at Devices > Enroll Device(s).

jamf-cli school setup

You'll be guided through:

  1. Profile name (default: school)
  2. School URL — e.g., https://tenant.jamfschool.com
  3. Network ID — from the Jamf School console
  4. API Key — hidden input, stored in the system keychain
  5. Platform API access (optional) — if yes, collects gateway region, tenant ID, client ID, and client secret for Platform API commands (blueprints, DDM reports)

Once complete:

jamf-cli school overview
jamf-cli school devices list
jamf-cli school classes list

# If platform credentials were configured:
jamf-cli school blueprints list

Setup flags

Flag Description
--url School instance URL (e.g., https://tenant.jamfschool.com)
--profile-name Profile name (default: school)

Credentials (network ID and API key) are always collected via interactive prompts. school setup requires interactive input and cannot be fully automated. For CI/CD environments, use environment variables directly (see Configuration & Profiles#Environment Variables).

Environment variable authentication

For quick ad-hoc use or CI pipelines, skip profiles entirely:

export JAMFSCHOOL_URL="https://tenant.jamfschool.com"
export JAMFSCHOOL_NETWORK_ID="your-network-id"
export JAMFSCHOOL_API_KEY="your-api-key"

jamf-cli school devices list

To also enable Platform API commands:

export JAMFSCHOOL_URL="https://tenant.jamfschool.com"
export JAMFSCHOOL_NETWORK_ID="your-network-id"
export JAMFSCHOOL_API_KEY="your-api-key"
export JAMFSCHOOL_PLATFORM_URL="https://eu.apigw.jamf.com"
export JAMF_CLIENT_ID="your-client-id"
export JAMF_CLIENT_SECRET="your-client-secret"
export JAMF_TENANT_ID="your-tenant-id"

jamf-cli school blueprints list

Note: JAMFSCHOOL_URL falls back to JAMF_URL if not set. Platform credentials use the shared JAMF_* variables.

Jamf Security Cloud Quick Start

Jamf Security Cloud (Radar) provisions a separate application ID/secret pair per API — Risk, Device Lifecycle, and Shared Signals & Events (SSE) each have their own "Security Integration" under Settings > Security Integrations in the Radar portal. Create integrations for whichever APIs you need before running setup.

jamf-cli security setup

You'll be guided through:

  1. Profile name (default: security)
  2. Risk API — application ID and secret (leave the application ID blank to skip)
  3. Device Lifecycle API — application ID and secret (leave blank to skip)
  4. Shared Signals & Events API — application ID and secret (leave blank to skip)

At least one pair is required. Secrets are stored in the system keychain. There is no URL to configure — all three APIs share Jamf's global production host, and tenancy is carried inside the credentials. Once complete:

jamf-cli security risk list
jamf-cli security stream get

Setup flags

Flag Description
--profile-name Profile name (default: security)

Credentials are always collected via interactive prompts with hidden input. security setup requires interactive input and cannot be run with --no-input. For CI/CD environments, use environment variables directly.

Environment variable authentication

For CI pipelines, skip profiles entirely by setting the credential pair(s) for the API(s) you use:

# Risk API
export JAMFSECURITY_RISK_CLIENT_ID="your-risk-application-id"
export JAMFSECURITY_RISK_CLIENT_SECRET="your-risk-application-secret"

# Device Lifecycle API
export JAMFSECURITY_LIFECYCLE_CLIENT_ID="your-lifecycle-application-id"
export JAMFSECURITY_LIFECYCLE_CLIENT_SECRET="your-lifecycle-application-secret"

# Shared Signals & Events API
export JAMFSECURITY_SSE_CLIENT_ID="your-sse-application-id"
export JAMFSECURITY_SSE_CLIENT_SECRET="your-sse-application-secret"

jamf-cli security risk list

Note: Each API's client ID and secret must both come from the same source — set both via env or neither. Configure only the API(s) you need; commands for an unconfigured API fail with a "run security setup" hint. See Configuration & Profiles#Jamf Security Cloud for the full variable list, including the optional JAMFSECURITY_URL / JAMFSECURITY_SSE_URL host overrides.

Jamf Pro Setup Details

Setup flags

All flags are optional — anything omitted will be prompted interactively.

Flag Description
--url Jamf Pro server URL
--from-file File containing one Jamf Pro URL per line (for multi-instance setup)
--scope read-only, standard, or full-admin
--profile-name Profile name (default: default; ignored with --from-file)
--rotate-credentials Regenerate client credentials for existing integrations

--url and --from-file are mutually exclusive.

Admin credentials (username and password) are always collected via interactive prompts with hidden input for the password. This prevents accidental exposure in shell history and process listings.

Note: pro setup requires interactive input and cannot be fully automated. For CI/CD environments, use environment variables directly or create a config profile with env: / file: secret references (see Configuration & Profiles).

Secrets are stored in the system keychain automatically. On systems without keychain access, use config add-profile with env: or file: references instead.

Multi-instance setup (MSPs)

For environments managing many Jamf Pro instances with shared admin credentials, use --from-file with a file containing one URL per line:

# instances.txt
school1.jamfcloud.com
school2.jamfcloud.com
school3.jamfcloud.com

jamf-cli pro setup \
  --from-file instances.txt \
  --scope standard

You'll be prompted once for admin credentials, which are reused across all instances. Profiles are auto-named pro-<subdomain> (e.g., pro-school1, pro-school2). If an instance fails, setup continues with the remaining instances and reports a summary at the end.

After setup, switch between instances with --profile:

jamf-cli -p pro-school1 pro overview
jamf-cli -p pro-school2 pro computers list

Idempotent setup

pro setup is safe to re-run. It checks whether the API role and integration already exist on the instance and updates them in place rather than creating duplicates. Existing client credentials are preserved by default so that other processes (CI pipelines, scripts, MJT) using the same integration are not disrupted.

To explicitly regenerate credentials (invalidating the old ones), pass --rotate-credentials:

jamf-cli pro setup --url https://jamf.company.com --rotate-credentials

Team usage

API integrations are named jamf-cli [<username>], so multiple team members can run setup against the same instance without colliding. The API role (jamf-cli-<scope>) is shared.

What the wizard does

Behind the scenes, pro setup performs these steps with the temporary bearer token from your admin credentials:

  1. Fetches available API privileges from the Jamf Pro instance
  2. Creates (or updates) an API role named jamf-cli-<scope> with the selected privilege set
  3. Creates (or updates) an API integration named jamf-cli [<username>] linked to that role
  4. Generates OAuth2 client credentials (client ID + secret) — skipped for existing integrations unless --rotate-credentials is passed
  5. Stores the client secret in the system keychain (see Secrets & Keychain)
  6. Saves the profile to the config file and sets it as the default (single instance) or auto-names it (multi-instance)

Manual Profile Configuration

If you already have API credentials (or prefer not to use the wizard), add a profile directly:

# Platform gateway profile (recommended — enables both Pro API and Platform API)
jamf-cli config add-profile prod \
  --url https://us.apigw.jamf.com \
  --auth-method platform \
  --tenant-id your-tenant-id
# You'll be prompted for client ID and client secret (hidden input)

# Direct instance profile (Pro API only)
jamf-cli config add-profile prod \
  --url https://jamf.company.com \
  --auth-method oauth2
# You'll be prompted for client ID and client secret (hidden input)

See Configuration & Profiles for full details on auth methods and profile management.

add-profile flags

Flag Description
--url Server URL — gateway URL for platform auth, instance URL for oauth2/token (required)
--auth-method platform, oauth2, or token (default: token)
--tenant-id Jamf tenant ID (required for platform auth method)

Credentials (token, client ID, client secret) are collected via interactive prompts with hidden input. This prevents accidental exposure in shell history and process listings.

For CI/CD environments where interactive input is not available, use env: or file: secret references directly in the config file (see Secrets & Keychain).

SSO / No local accounts

If your Jamf Pro instance uses SSO and local admin accounts are disabled or unavailable, pro setup won't work — it requires a local username and password to bootstrap credentials. The solution is the same pattern Jamf Protect uses: create an API client manually in the Jamf Pro console, then configure the CLI with those credentials.

Step 1 — Create an API role

  1. In Jamf Pro, go to Settings > System > API roles and clients
  2. Click New under the API Roles tab
  3. Give it a name (e.g., jamf-cli)
  4. Assign the privileges you need — refer to the scope options above for a guide to what each level covers
  5. Save

Step 2 — Create an API client

  1. Still in Settings > System > API roles and clients, select the API Clients tab
  2. Click New
  3. Give it a display name (e.g., jamf-cli)
  4. Assign it to the API role you just created
  5. Set an appropriate access token lifetime
  6. Save, then click Generate Client Secret
  7. Copy both the Client ID and Client Secret — the secret is only shown once

Step 3 — Configure the CLI

jamf-cli config add-profile prod \
  --url https://jamf.company.com \
  --auth-method oauth2
# You'll be prompted for client ID and client secret (hidden input)

Once saved, the profile works exactly like one created by pro setup. Run jamf-cli config validate --connectivity to confirm authentication is working.

Validate Your Configuration

Run config validate to verify the config file structure, secret resolution, and optionally test server reachability:

jamf-cli config validate
jamf-cli config validate --connectivity

See Configuration & Profiles#Validate for example output and profile management commands.

Config File Location

The config file follows XDG conventions:

Priority Path
1 $XDG_CONFIG_HOME/jamf-cli/config.yaml
2 ~/.config/jamf-cli/config.yaml (XDG default)

Use jamf-cli config path to see which file is active.

Shell Completion

Auto-install

jamf-cli completion install

Detects your shell (bash, zsh, or fish) and installs completions to the standard location.

Manual install

# Bash (Linux)
jamf-cli completion bash > /etc/bash_completion.d/jamf-cli

# Bash (macOS with Homebrew)
jamf-cli completion bash > $(brew --prefix)/etc/bash_completion.d/jamf-cli

# Zsh
jamf-cli completion zsh > "${fpath[1]}/_jamf-cli"

# Fish
jamf-cli completion fish > ~/.config/fish/completions/jamf-cli.fish

# PowerShell
jamf-cli completion powershell | Out-String | Invoke-Expression

Next Steps

Repository · Issues · Releases

jamf-cli Wiki

Products

  • Jamf Pro — jamf-cli pro
  • Jamf Platform API — jamf-cli pro (platform commands)
  • Jamf Protect — jamf-cli protect
  • Jamf School — jamf-cli school
  • Jamf Security Cloud — jamf-cli security

Clone this wiki locally