argocd proj

Manage Argo CD projects for organizing applications and enforcing policies

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 applications
• RBAC policies for access control
• Source repositories whitelist
• Destination clusters and namespaces whitelist
• Resource allow/deny lists (which Kubernetes resources can be deployed)
• Orphaned resources monitoring
• Sync 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:

--description · string

Project description

--src · string[]

Permitted source repository URLs (supports wildcards)

--dest · string[]

Permitted destination in format: SERVER,NAMESPACE

--allow-cluster-resource · string[]

Allow cluster-scoped resource (e.g., Namespace, ClusterRole)

--allow-namespaced-resource · string[]

Allow namespaced resource (e.g., Deployment, Service)

--orphaned-resources-warn · boolean

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 \
  '*'

server · string · required

Kubernetes cluster server URL

namespace · string · required

Target namespace (supports wildcards)

--name · string

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 application
• create - Create application
• update - Update application
• delete - Delete application
• sync - Sync application
• override - 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

--schedule · string · required

Cron schedule (e.g., “0 9 * * 1-5” for weekdays 9am)

--duration · string · required

Window duration (e.g., 1h, 30m, 8h)

--kind · string · default: "allow"

Window type: allow or deny

--applications · string[]

Applications to which window applies (supports wildcards)

--namespaces · string[]

Namespaces to which window applies

--clusters · string[]

Clusters to which window applies

--manual-sync · boolean

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