[DOCS] Explicitly link `--allowedTools` CLI flags to `permissions` settings

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/settings#permission-settings - https://code.claude.com/docs/en/cli-reference

Section/Topic

The "Permission settings" table in the Settings documentation.

Current Documentation

In settings.md, the table lists:

• allow: "Array of permission rules to allow tool use. Note: Bash rules use prefix matching, not regex"
• deny: "Array of permission rules to deny tool use..."

Separately, in cli-reference.md, the documentation lists:

• --allowedTools: "Tools that execute without prompting for permission..."
• --disallowedTools: "Tools that are removed from the model's context..."

What's Wrong or Missing?

The documentation does not explicitly link these two configuration methods. A user familiar with the --allowedTools CLI flag who wants to make that configuration persistent in settings.json might not immediately realize that permissions.allow is the direct equivalent. The mapping between the CLI flags and the JSON configuration keys is implied but not stated.

Suggested Improvement

In the Permission settings table on the Settings page (https://code.claude.com/docs/en/settings#permission-settings), update the descriptions to reference the CLI equivalents:

• Key: allow
  Description: Array of permission rules to allow tool use. Corresponds to the --allowedTools CLI flag.
• Key: deny
  Description: Array of permission rules to deny tool use. Corresponds to the --disallowedTools CLI flag.

Impact

High - Prevents users from using a feature

Additional Context

Mapping clarification:

• CLI: --allowedTools -> Settings: permissions.allow
• CLI: --disallowedTools -> Settings: permissions.deny

[coygeek]

Thank you for the update to the documentation. I have reviewed the latest versions of the Settings and CLI Reference pages to see if the mapping between CLI flags and persistent configuration keys has been clarified.

What’s FIXED

• Contextual Linking in CLI Reference: The documentation at https://code.claude.com/docs/en/cli-reference now includes a direct link for the --allowedTools flag to the "permission rule syntax" section within the settings documentation. This improves navigation for users looking to understand how to format rules.
• Subagent Permission Mapping: In the "Task (Subagents)" section of https://code.claude.com/docs/en/iam#tool-specific-permission-rules, the documentation now explicitly states: "Add these rules to the deny array in your settings or use the --disallowedTools CLI flag to disable specific agents." This provides the exact type of explicit mapping I requested, albeit only for one specific use case.

What’s UNRESOLVED

• Missing Mapping in Primary Settings Table: The primary "Permission settings" table at https://code.claude.com/docs/en/settings#permission-settings still lacks explicit references to the corresponding CLI flags. The current descriptions for allow and deny focus on functionality but do not inform the user that these are the persistent equivalents of --allowedTools and --disallowedTools.
• General Lack of Flag-to-Key Reference: Beyond the subagent section, there is no centralized note or table informing users that CLI flags generally act as temporary overrides for specific JSON keys in ~/.claude/settings.json. For a user trying to migrate a one-off command (e.g., claude --allowedTools "Read") into a permanent project configuration, the documentation still requires them to infer that permissions.allow is the correct destination.

Conclusion

I am keeping this issue open. While the documentation has improved with better internal linking, the specific request to update the "Permission settings" table with CLI flag equivalents has not been addressed. To fully resolve this, the table at https://code.claude.com/docs/en/settings#permission-settings should be updated so that:

1. The allow key description mentions it corresponds to --allowedTools.
2. The deny key description mentions it corresponds to --disallowedTools.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.