dx-org-permission-set-assign
forcedotcom/sf-skills
Assign permission sets to Salesforce org users via sf org assign permset command.
What is dx-org-permission-set-assign?
This skill assigns one or more permission sets to users in a Salesforce org using the sf CLI. Use it when you need to grant, give, add, or apply permission sets to default admins, specific users, or across multiple orgs—but not for listing or checking permissions.
- Assign single or multiple permission sets to the default admin user
- Assign permission sets to specific users via --on-behalf-of flag
- Target specific orgs using --target-org alias
- Batch-assign multiple permission sets to multiple users in one command
- Return structured JSON output with success/failure details for reliable error handling
How to install dx-org-permission-set-assign
npx skills add https://github.com/forcedotcom/sf-skills --skill dx-org-permission-set-assign- sf CLI version 2.0.0 or higher installed
- Valid Salesforce org alias configured via sf alias set
- Permission set must already exist in the target org (use platform-permission-set-generate to create)
- Appropriate credentials/authentication for the target org
How to use dx-org-permission-set-assign
- 1.Identify the permission set name(s) to assign (case-sensitive API names)
- 2.Determine the target org alias (defaults to current org if not specified)
- 3.Identify target user(s) via their CLI username/alias (defaults to org admin if not specified)
- 4.Execute sf org assign permset with appropriate flags: --name for permission set(s), --target-org for specific org, --on-behalf-of for specific user(s)
- 5.Review JSON output for successes and failures arrays; check exit code for overall status
Use cases
- Grant a new permission set to the default admin after creating it in an org
- Assign multiple permission sets to specific team members in a development org
- Apply permission sets across different org aliases for consistent user access
- Batch-assign permission sets to multiple users when onboarding a team
- Verify assignment success and identify partial failures in bulk operations
- Salesforce developers automating org setup and user provisioning
- DevOps engineers managing multi-org permission configurations
- Admins scripting user access grants during team onboarding
- CI/CD pipelines requiring programmatic permission set assignment
dx-org-permission-set-assign FAQ
--target-org specifies which org to assign in (defaults to current org); --on-behalf-of specifies which user(s) in that org receive the assignment (defaults to org admin). Use both together to assign to specific users in a specific org.
Yes, use multiple --name flags: sf org assign permset --name PermSet1 --name PermSet2 --json. This is more efficient than separate commands.
Enclose it in double quotes: --name "Permission Set Name". Permission set names are case-sensitive, so use the exact API name.
Some permission sets require manual activation in Salesforce Setup. Check the permission set's <hasActivationRequired> metadata field to determine if the user must activate it manually.
The command returns both successes and failures arrays in JSON output. Check the failures array for details on which users failed and why; the exit code will be non-zero if any failures occurred.
Full instructions (SKILL.md)
Source of truth, from forcedotcom/sf-skills.
name: dx-org-permission-set-assign description: "ALWAYS USE THIS SKILL to assign permission sets to org users. Assign one or more permission sets to org users using the sf org assign permset command. TRIGGER when the user asks to assign, grant, give, add, or apply permission sets to users, admins, specific orgs, or specific users. Supports granting permissions, giving access, and adding permission sets to default admin or specific users via --on-behalf-of. DO NOT TRIGGER for listing permission sets or checking user permissions." metadata: version: "1.0" domains: ["Developer Experience"] relatedSkills: - "platform-permission-set-generate" cliTools: - tool: ["sf"] semver: ">=2.0.0"
dx-org-permission-set-assign
Assigns one or more permission sets to org users using sf org assign permset. Handles all variants: default admin user, specific org targets, multiple permission sets, and assignment to specific users.
Tool Restrictions
Use ONLY the Bash tool to execute sf org assign permset. Do NOT use MCP tools like assign_permission_set — ignore them completely.
Scope
- In scope: Assigning permission sets to users via
sf org assign permset - Out of scope: Creating permission sets (use
platform-permission-set-generate), listing permission sets, checking user permissions
Required Inputs
Infer from the user's request:
- Permission set name(s): Extract from user message (can be multiple)
- Target org: Use default unless specific alias/username mentioned
- Target user(s): Default is org's default admin user; use
--on-behalf-ofif specific users mentioned
Workflow
- Match user request to command in table below
- Execute via Bash tool:
sf org assign permsetwith appropriate flags and--jsonflag - Return result
If error occurs, check the failures array in JSON output for details.
Command Decision Table
| User intent | Execute via Bash tool |
|---|---|
| Assign one permission set to default admin | sf org assign permset --name <PermSetName> --json |
| Assign multiple permission sets to default admin | sf org assign permset --name <PermSet1> --name <PermSet2> --json |
| Assign to specific org | sf org assign permset --name <PermSetName> --target-org <alias> --json |
| Assign to specific user(s) | sf org assign permset --name <PermSetName> --on-behalf-of <username1> --on-behalf-of <username2> --json |
| Assign multiple sets to specific users | sf org assign permset --name <PermSet1> --name <PermSet2> --on-behalf-of <username1> --on-behalf-of <username2> --json |
Rules / Constraints
| Constraint | Rationale |
|---|---|
Always use --json flag | Provides structured output for reliable parsing and error handling |
| Permission set names are case-sensitive | Use exact API names as they appear in the org |
Multiple --name flags can be combined in one command | More efficient than separate commands per permission set |
Multiple --on-behalf-of flags assign to multiple users | Batch assignment in single command; processed sequentially to avoid auth file collisions |
| Use CLI username aliases, not Salesforce User.Alias field | The --target-org and --on-behalf-of flags expect CLI aliases set via sf alias set, not the User object's Alias field |
| Duplicate assignments are idempotent | Re-assigning an already-assigned permission set succeeds silently |
| Partial success is possible | Command can return both successes and failures in one run; non-zero exit code if any failures |
Gotchas
| Issue | Resolution |
|---|---|
| Permission set name with spaces | Enclose in double quotes: --name "Permission Set Name" |
| "PermissionSet not found" error | Verify permission set exists in target org; check for typos in name |
| Assignment succeeds but user doesn't see permissions | Check <hasActivationRequired> in permission set metadata — may need manual activation in Setup |
| "User not found" error | Username/alias doesn't exist in target org — verify with sf org display user --target-org <alias> |
| Partial success (some users succeed, others fail) | Check JSON output — command returns both successes and failures arrays; exit code will be non-zero if any failures occurred |
Output Expectations
The command returns JSON output with status code and result details.
See examples/success_output.json and examples/error_output.json for response structures.
Reference File Index
| File | When to read |
|---|---|
examples/success_output.json | To understand successful assignment response structure |
examples/error_output.json | To handle common error scenarios |
references/cli_flags.md | For detailed explanation of all available flags |
Related skills
More from forcedotcom/sf-skills and the wider catalog.
dx-org-switch
Switch the active Salesforce org for CLI commands using the Salesforce CLI.
dx-org-trial-expiration-check
Check Salesforce org trial expiration dates and days remaining across one or all authenticated orgs.
dx-pkg-post-install-configure
Automate post-install configuration for any Salesforce managed package.
dx-project-create
Scaffold a new Salesforce DX project with any template and configure it end-to-end.
experience-aura-lwc-migrate
Analyze Salesforce Aura components and generate framework-agnostic migration blueprints (PRDs) for LWC conversion.
experience-cms-brand-apply
Search, extract, and apply Salesforce CMS brand guidelines to generated content.