Problem:
I’m new to pulp and trying to understand how to manage it via cli. I.e. it’s not clear what --staff option gives to a user and what it’s needed for.
Expected outcome:
It would be nice to have full cli documentation with every command explained
Pulpcore version:
3.80.0
Pulp plugins installed and their versions:
Pulp3 Command Line Interface, Version 0.32.3
Plugin Versions:
common: 0.32.3
Operating system - distribution and version:
MacOS
Every pulp CLI subcommand knows the --help option. To the best of my knowledge, what is not documented there is not documented.
Yeah, I know about --help, this is the first thing I used it. But in some cases it’s not clear what this option for, like --staff. I had to search the whole documentation just to found
“Having disabled the token authentication, only users with staff privileges (i.e., administrators) are allowed to push content to the registry.”
@DenisBY We have some docs on the CLI: Using the CLI - Pulp Project, but mainly it’s through each plugin’s documentation that shows off the available commands. You will find that we try to maintain the same command structure across plugins so that the syntax between plugins feels familiar.
As for your second part about the --staff option, unfortunately that is not correct and we really should fix the documentation on it (and remove the option from the API & CLI). Staff comes from the default Django code, but the Pulp project doesn’t actually use it. We just have superusers (admins) and everyone else whose permissions are managed by the RBAC system. We also don’t use the --active flag for users either.
Hello all,
Apologies for reviving this old topic, but I’m unable to create a new one at the moment.
I recently installed Pulp CLI 0.39.3 along with the latest pulpcore 3.113.0 to enable synchronization from a Git repository, as described in the official documentation:
pulp file remote --type git create --name $REMOTE_NAME --url $GIT_URL
It seems that the --type git option is not recognized by the Pulp CLI. When I attempt to use it, I encounter the following error message:
“Error: Invalid value for ‘-t’ / ‘–type’: ‘git’ is not ‘file’.”
Here is the list of the installed python packages:
python3 -m pip freeze | grep pulp
pulp-cli==0.39.3
pulp-glue==0.39.3
pulpcore==3.113.0
Could you please let me know if there is any detailed documentation or guidance on how to configure Pulp CLI for Git synchronization? I’d greatly appreciate your help.
Thank you in advance
The thing to check is pulp file remote --help. For me this shows:
Options:
-t, --type [file]
Suggesting that the installed version of pulp-cli does not know any file remote types other than file.
Given the relevant pulp_file docs speak of --type git this either means the pulp-cli version we are using is too old, or else the version has a bug that breaks --type git. I have:
$ pulp --version
Pulp3 Command Line Interface, Version 0.36.2.dev
Plugin Versions:
deb: 0.5.0.dev
common: 0.36.2.dev
Which is quite a bit older than what you have.
A global Pulp CLI docs exists here: Pulp 3 CLI Docs - Pulp Project
But for the most part you would be expected to use the --help option on your installed version of Pulp CLI, which exists for each sub-command of Pulp CLI.
This is my bad. I added the git remote syncing and opened a PR for the CLI (https://github.com/pulp/pulp-cli/pull/1322), but never finished it. Let me work on that, in the meantime you’ll have to use the API to create and sync git remotes.
pulp file repository create --name pulpcore
http POST localhost:5001/pulp/api/v3/remotes/file/git/ \
name=pulpcore url=https://github.com/pulp/pulpcore.git
http POST localhost:5001/pulp/api/v3/repositories/file/file/{pulpcore_repo_pk}/sync/ remote={pulpcore_remote_href}
Hi @gerrod ,
Thank you for your response. Could you please update the documentation to indicate that this feature is not yet available in the latest release?
If i generate a PULP Manifest file, do you think that it will be possible for me to use the PULP CLI as given in this example ?
#!/usr/bin/env bash
export REMOTE_NAME=$(head /dev/urandom | tr -dc a-z | head -c5)
echo “Creating a remote that points to an external source of files.”
pulp file remote create --name $REMOTE_NAME
–url ‘${GIT_URL}/PULP_MANIFEST’
echo “Inspecting new Remote.”
pulp file remote show --name $REMOTE_NAME
So you are trying to sync a git_url (probably github?) and you are asking if adding a PULP_MANIFEST to the git repo would allow Pulp to sync it using normal file remotes? Short answer - no. Long answer - yes, if you use the right url, but this is a hack specific to github and you really should use git remotes instead.
Say we were to add a PULP_MANIFEST to https://github.com/pulp/pulpcore in the root of the repo, then if we set the file remote url to https://raw.githubusercontent.com/pulp/pulpcore/refs/heads/main/PULP_MANIFEST Pulp should be able to sync the files of the git repo. However, sites like GitHub aren’t built to act like a normal file repository (they don’t store files, they store git objects! Git - Git Objects), so this is taking advantage of GitHub’s raw API and could fail from things like rate-limits.
Another option is downloading the repository as a zip file onto the Pulp machine, add a PULP_MANIFEST to that local folder and then add a file remote with the url file://local/git/repo/PULP_MANIFEST. Note for this to work you need the local/git/repo path to be a part of the ALLOWED_IMPORT_PATHS setting.
I think both scripting to talk to the Pulp API directly (for example using @gerrod’s http based instructions from three posts up), or else installing Pulp CLI from gerrod’s PR that adds the --type git option to Pulp CLI sounds like a better solution to me, than it is to add a PULP_MANIFEST to a git repository.
It is actually pretty easy to install Pulp CLI into a virtual python environment from a PR, and then you can simply start using the feature from that PR. Assuming it works, you can eaven leave a review with your findings on the PR to help speed it along.
Hello,
I test the solution based in the API as suggestrd by @gerrod but i have few problems with the last command to synchronize the repository
‘i get Server Error (500)’ as response and when i check the docker pulp server logs i can see these errors:
File “/usr/local/lib/python3.11/site-packages/pulpcore/app/models/fields.py”, line 112, in from_db_value
value = force_str(_fernet().decrypt(force_bytes(value)))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File “/usr/local/lib64/python3.11/site-packages/cryptography/fernet.py”, line 206, in decrypt
raise InvalidToken
cryptography.fernet.InvalidToken
I note that i get the same error message if i try to list file remotes using the CLI “pulp file remote list”
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File “/usr/local/lib64/python3.11/site-packages/cryptography/fernet.py”, line 206, in decrypt
raise InvalidToken
cryptography.fernet.InvalidToken
(‘pulp [fe98xxxxxxxxxxxxx]: ::1 - admin [11/Jun/2026:12:45:07 +0000] “GET /pulp/api/v3/remotes/file/file/?offset=0&limit=25 HTTP/1.0” 500 145 “-” “Pulp-CLI/0.40.1”’,)
But the command line “pulp file reposity list” works well !
Any idea please ?
Thank you in advance for your help
This error typically means Pulp loaded the wrong DB_ENCRYPTION_KEY and can not read the encrypted fields on the Remote (username, password, etc…) The setting, by default, is set to a file at /etc/pulp/certs/database_fields.symmetric.key. The single container pulp/pulp will auto create this file if it is not present on the system, and the command we instruct users to run the container mounts the container’s /etc/pulp to your local machine’s $(pwd)/settings/ folder. Thus the key should be saved in between container runs, but if you delete it or move to a different directory without moving the certs folder with it then a new key will be generated and any old encrypted fields in the database will be unreadable. If you are using the minimal images, then the key should be under the compose/assets/certs directory. Again if this file changes or is missing you will run into the same problem.
If you can’t find the original file you are going to need to delete the offending entries from the database.
docker exec -it pulp pulpcore-manager shell
# Loads a python shell
from pulpcore.app.models import Remote
Remote.objects.all().delete()
If you want you can replace .all() with .filter(pk='{remote_pk}' or .filter(name='osconf-t3)`, but your git remote might not be the offending remote, it could be an earlier created one. It’s a bit inconvenient to delete all the remotes, but recreating them is cheaper than starting your Pulp instance from scratch again. One thing to note is that if you delete any remote that was on_demand, then any on_demand content that was synced with that remote will be broken until you recreate the remote and reperform the sync.
Hello @gerrod,
Thank you for your assistance. I recreated the Pulp Git repository and successfully synchronized it, allowing me to create a publication.
However, i wasn’t able to clean up the old repository ’ osconf-t3 as i dont want to remove all remotes. When i use Remote.objects…filter(pk=’{remote_pk}’).delete(), i get this error
“/usr/local/lib64/python3.11/site-packages/cryptography/fernet.py”, line 206, in decrypt raise InvalidToken cryptography.fernet.InvalidToken
In addition, i believe that this remaining remote git repository osconf-t3 causes the Pulp server worker to crash periodically with the following error:
File “/usr/local/lib/python3.11/site-packages/django/db/backends/postgresql/base.py”, line 332, in get_new_connection
connection = self.Database.connect(**conn_params)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File “/usr/local/lib/python3.11/site-packages/psycopg/connection.py”, line 122, in connect
raise last_ex.with_traceback(None)
django.db.utils.OperationalError: connection timeout expired
connection timeout expired[2026-06-16 05:58:10 +0000] [44602] [INFO] Worker exiting (pid: 44602)
[2026-06-16 05:58:11 +0000] [44583] [ERROR] Worker (pid:44597) exited with code 3.
[2026-06-16 05:58:11 +0000] [44583] [ERROR] Worker (pid:44602) exited with code 3.
Traceback (most recent call last):
File “/usr/local/lib/python3.11/site-packages/gunicorn/arbiter.py”, line 246, in run
handler()
File “/usr/local/lib/python3.11/site-packages/gunicorn/arbiter.py”, line 271, in handle_chld
self.reap_workers()
File “/usr/local/lib/python3.11/site-packages/gunicorn/arbiter.py”, line 641, in reap_workers
raise HaltServer(reason, self.WORKER_BOOT_ERROR)
gunicorn.errors.HaltServer: <HaltServer ‘Worker failed to boot.’ 3>
When this error occurs, the Pulp server becomes unreachable, even after multiple attempts to restart the Docker container. The only way I’ve been able to resolve the issue is by redeploying the virtual machine hosting the Pulp container.
Do you have any suggestions to resolve this issue?
Is there a way to delete the remaining Git repository, which might be causing this problem, directly from the database and the bucket ? or if i find the old database_fields.symmetric.key, how can i reload it temporary to the pulp container just to clean up the old remote repositories and after that switch back to the newest database_fields.symmetric.key ?
Thank you in advance
Best regards
@mda78 Sorry for the late reply, was on vacation. Can you try this?
Remote.objects.filter(pk='{remote_pk}').only("pk").delete()
Basically we want to try to avoid Django ORM doing anything extra behind the scenes, loading the encrypted fields that can’t be loaded. Let me know if this doesn’t work, I can write some commands to run in the database shell to delete the remote and avoid Django entirely.