The argocd proj (or argocd project) command manages projects, which provide logical grouping of applications with RBAC policies, resource restrictions, and access controls.
Quick Examples # List all projects argocd proj list # Create a new project argocd proj create my-project # Delete a project argocd proj delete my-project # Edit project settings argocd proj edit my-project
Understanding Projects Projects provide:
Logical grouping of applicationsRBAC policies for access controlSource repositories whitelistDestination clusters and namespaces whitelistResource allow/deny lists (which Kubernetes resources can be deployed)Orphaned resources monitoringSync windows for controlling when deployments can occur
The default project exists in all Argo CD installations and has no restrictions by default.
Subcommands create Create a new project.
# Basic project creation argocd proj create my-project # Create with description argocd proj create my-project --description "Production applications" # Create with source repositories argocd proj create my-project \ --src https://github.com/myorg/ * \ --src https://charts.helm.sh/stable # Create with destinations argocd proj create my-project \ --dest https://kubernetes.default.svc,my-namespace \ --dest https://prod-cluster,prod- * # Create allowing specific resources argocd proj create my-project \ --allow-cluster-resource Namespace \ --allow-namespaced-resource Deployment \ --allow-namespaced-resource Service
Key Flags: Permitted source repository URLs (supports wildcards)
Permitted destination in format: SERVER,NAMESPACE
Allow cluster-scoped resource (e.g., Namespace, ClusterRole)
--allow-namespaced-resource
Allow namespaced resource (e.g., Deployment, Service)
--orphaned-resources-warn
Warn on orphaned resources
list List all projects.
# List projects argocd proj list # List as JSON argocd proj list -o json # List as YAML argocd proj list -o yaml
Output: NAME DESCRIPTION DESTINATIONS SOURCES CLUSTER-RESOURCE-WHITELIST NAMESPACE-RESOURCE-WHITELIST SIGNATURE-KEYS ORPHANED-RESOURCES default *,* * */* */* disabled production Production applications 2 3 5 resources 10 resources warn dev-team Development team applications 1 2 */* */* disabled
get Get detailed information about a project.
# Get project details argocd proj get my-project # Get as YAML argocd proj get my-project -o yaml # Get as JSON argocd proj get my-project -o json
Output: Name: my-project Description: Production applications Orphaned Resources: enabled (warn) Source Repositories: https://github.com/myorg/* https://charts.helm.sh/stable Destinations: Server Namespace Name https://kubernetes.default.svc prod-* in-cluster https://prod-cluster.example.com * production Allowed Cluster Resources: GROUP KIND * Namespace * ClusterRole * ClusterRoleBinding Allowed Namespace Resources: GROUP KIND * Deployment * Service * ConfigMap * Secret Project Roles: NAME POLICIES admin Full access developer Read-only access
set Update project settings.
# Set description argocd proj set my-project --description "Updated description" # Enable orphaned resources warning argocd proj set my-project --orphaned-resources-warn
edit Edit project in your default editor.
# Edit project manifest argocd proj edit my-project
This opens the project YAML in your $EDITOR.
delete Delete a project.
# Delete project argocd proj delete my-project # Delete without confirmation argocd proj delete my-project --yes
You cannot delete a project that has applications. Delete or move all applications first.
Managing Sources add-source Add permitted source repository.
# Add specific repository argocd proj add-source my-project https://github.com/myorg/myrepo.git # Add with wildcard argocd proj add-source my-project 'https://github.com/myorg/*' # Add Helm repository argocd proj add-source my-project https://charts.bitnami.com/bitnami
remove-source Remove permitted source repository.
argocd proj remove-source my-project https://github.com/myorg/oldrepo.git
add-source-namespace Add source namespace for ApplicationSet.
argocd proj add-source-namespace my-project argocd argocd proj add-source-namespace my-project my-apps
remove-source-namespace Remove source namespace.
argocd proj remove-source-namespace my-project old-namespace
Managing Destinations add-destination Add permitted destination cluster and namespace.
# Add specific cluster and namespace argocd proj add-destination my-project \ https://kubernetes.default.svc \ production # Add with namespace wildcard argocd proj add-destination my-project \ https://prod-cluster.example.com \ 'prod-*' # Add allowing all namespaces argocd proj add-destination my-project \ https://kubernetes.default.svc \ '*'
Kubernetes cluster server URL
Target namespace (supports wildcards)
Cluster name instead of server URL
remove-destination Remove permitted destination.
argocd proj remove-destination my-project \ https://old-cluster.example.com \ old-namespace
add-destination-service-account Add service account for destination.
argocd proj add-destination-service-account my-project \ https://kubernetes.default.svc \ production \ deployer
remove-destination-service-account Remove service account from destination.
argocd proj remove-destination-service-account my-project \ https://kubernetes.default.svc \ production \ old-deployer
Resource Whitelists/Blacklists allow-cluster-resource Add cluster-scoped resource to allow list.
# Allow specific cluster resources argocd proj allow-cluster-resource my-project Namespace argocd proj allow-cluster-resource my-project ClusterRole argocd proj allow-cluster-resource my-project CustomResourceDefinition # Allow with API group argocd proj allow-cluster-resource my-project PersistentVolume --group '' argocd proj allow-cluster-resource my-project ClusterIssuer --group cert-manager.io
deny-cluster-resource Add cluster-scoped resource to deny list.
argocd proj deny-cluster-resource my-project ClusterRoleBinding
allow-namespace-resource Add namespaced resource to allow list.
# Allow common resources argocd proj allow-namespace-resource my-project Deployment argocd proj allow-namespace-resource my-project Service argocd proj allow-namespace-resource my-project ConfigMap argocd proj allow-namespace-resource my-project Secret # Allow with API group argocd proj allow-namespace-resource my-project Certificate --group cert-manager.io argocd proj allow-namespace-resource my-project Rollout --group argoproj.io
deny-namespace-resource Add namespaced resource to deny list.
argocd proj deny-namespace-resource my-project NetworkPolicy
Project Roles Manage RBAC roles within a project.
role create Create a new project role.
# Create role argocd proj role create my-project developer # Create with description argocd proj role create my-project ops-team \ --description "Operations team access"
role list List project roles.
argocd proj role list my-project
Output: NAME DESCRIPTION admin Project administrators developer Developer access ci-cd CI/CD service account
role get Get role details.
argocd proj role get my-project developer
role delete Delete a project role.
argocd proj role delete my-project old-role
role add-policy Add policy to project role.
# Allow getting any application argocd proj role add-policy my-project developer \ --action get \ --permission allow \ --object '*' # Allow syncing specific applications argocd proj role add-policy my-project developer \ --action sync \ --permission allow \ --object 'my-project/my-app' # Multiple permissions argocd proj role add-policy my-project admin \ --action '*' \ --permission allow \ --object '*'
Policy Actions:
get - View applicationcreate - Create applicationupdate - Update applicationdelete - Delete applicationsync - Sync applicationoverride - Override application parameters* - All actions
role remove-policy Remove policy from project role.
argocd proj role remove-policy my-project developer \ --action sync \ --object 'my-project/old-app'
role add-group Associate SSO group with project role.
# Add OIDC/SAML group argocd proj role add-group my-project developer engineering-team argocd proj role add-group my-project admin platform-admins
role remove-group Remove SSO group from project role.
argocd proj role remove-group my-project developer old-team
role create-token Create authentication token for project role.
# Create token argocd proj role create-token my-project ci-cd # Create with expiration argocd proj role create-token my-project ci-cd --expires-in 90d # Create with specific ID argocd proj role create-token my-project ci-cd --id github-actions
Output: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
role list-tokens List tokens for a project role.
argocd proj role list-tokens my-project ci-cd
role delete-token Delete authentication token.
argocd proj role delete-token my-project ci-cd 1234567890
Sync Windows Control when applications can be synced.
windows add Add a sync window.
# Allow sync during business hours argocd proj windows add my-project \ --schedule "0 9 * * 1-5" \ --duration 8h \ --applications '*' # Deny sync during maintenance argocd proj windows add my-project \ --kind deny \ --schedule "0 2 * * 0" \ --duration 4h \ --applications '*' # Allow manual sync only argocd proj windows add my-project \ --schedule "0 0 * * *" \ --duration 24h \ --manual-sync
Cron schedule (e.g., “0 9 * * 1-5” for weekdays 9am)
Window duration (e.g., 1h, 30m, 8h)
Window type: allow or deny
Applications to which window applies (supports wildcards)
Namespaces to which window applies
Clusters to which window applies
Allow manual sync during this window
windows list List sync windows.
argocd proj windows list my-project
windows delete Delete a sync window.
argocd proj windows delete my-project 0
windows enable-manual-sync / disable-manual-sync Control manual sync in windows.
# Enable manual sync for window argocd proj windows enable-manual-sync my-project 0 # Disable manual sync argocd proj windows disable-manual-sync my-project 0
Common Workflows Create Production Project # Create project argocd proj create production \ --description "Production applications and infrastructure" # Add source repositories argocd proj add-source production 'https://github.com/myorg/prod-apps/*' argocd proj add-source production 'https://charts.helm.sh/stable' # Add destination clusters argocd proj add-destination production https://prod-us-east.example.com '*' argocd proj add-destination production https://prod-us-west.example.com '*' # Allow standard resources argocd proj allow-cluster-resource production Namespace argocd proj allow-namespace-resource production Deployment argocd proj allow-namespace-resource production Service argocd proj allow-namespace-resource production ConfigMap argocd proj allow-namespace-resource production Secret argocd proj allow-namespace-resource production Ingress # Add maintenance window argocd proj windows add production \ --kind deny \ --schedule "0 2 * * 0" \ --duration 4h \ --applications '*'
Create Development Project # Create project with relaxed permissions argocd proj create development \ --description "Development and testing applications" # Allow any source argocd proj add-source development '*' # Allow dev clusters and namespaces argocd proj add-destination development https://dev-cluster.example.com 'dev-*' argocd proj add-destination development https://dev-cluster.example.com 'test-*' # Allow all resources (development only!) argocd proj allow-cluster-resource development '*' --group '*' argocd proj allow-namespace-resource development '*' --group '*'
Setup RBAC for Team # Create team role argocd proj role create my-project developers # Add policies argocd proj role add-policy my-project developers \ --action get --permission allow --object '*' argocd proj role add-policy my-project developers \ --action sync --permission allow --object '*' argocd proj role add-policy my-project developers \ --action update --permission allow --object '*' # Link to SSO group argocd proj role add-group my-project developers engineering-team # Create token for CI/CD argocd proj role create-token my-project developers --id github-actions
Best Practices
Use separate projects for different environments (prod, staging, dev)
Define explicit source repositories instead of using wildcards
Use resource whitelists to enforce governance
Leverage sync windows for production change management
Create role-based access with SSO group integration
Use project tokens for CI/CD pipelines
Monitor orphaned resources in production projects
Document project policies and intended usage
Next Steps
App Commands Create applications within projects
Account Commands Manage user accounts and permissions