CLI reference

oa is the command-line client of the REST API. For login, the config file and worked examples see CLI. Global flags go before the command. Each command group below shows its usage as printed by oa help; commands that parse flags list them as printed by oa COMMAND --help (the flag package accepts both -flag and --flag).

Usage

text

oa [--server URL] [--token TOKEN] [--format table|json] <command> [args]

Global flags

text

--server    Server URL  (default: http://localhost:8080, env: OA_SERVER)
--token     API token   (env: OA_TOKEN)
--format    Output format: table|json  (default: table)

Environment variables

Variable	Named by
`OA_GPG_PASSPHRASE`	`oa gpg import`
`OA_IMPORT_SOURCE_TOKEN`	`oa import artifactory`, `oa import nexus`
`OA_IMPORT_SOURCE_USER`	`oa import artifactory`, `oa import nexus`
`OA_SERVER`	`--server`
`OA_TOKEN`	`--token`
`OA_WEBHOOK_SECRET`	`oa webhook create`

Auth

text

auth login [--server URL] [--username U] [--password-stdin]
                                   Login with username/password (prompted without echo) or token
auth logout [--revoke --username U --password-stdin]
                                   Clear saved credentials (--revoke also revokes the server-side token)
auth whoami                        Show current user
auth passwd [--password-stdin]     Change your password (stdin: current, then new, one per line)
auth token list                    List your personal API tokens
auth token create --name N [--kind access|deploy] [--username U] [--password-stdin]
                                   Create a personal API token (signs in with your password)
auth token revoke <id> [--username U] [--password-stdin]
                                   Revoke a personal API token (signs in with your password)

`oa auth login`

Flag	Value	Description
`-password`	`string`	removed; use --password-stdin
`-password-stdin`	none	Read the password from stdin
`-server`	`string`	Server URL (default "http://localhost:8080")
`-username`	`string`	Username (required with --password-stdin)

`oa auth logout`

Flag	Value	Description
`-password-stdin`	none	Read the password from stdin (with --revoke)
`-revoke`	none	Also revoke the saved token on the server (needs --username and --password-stdin)
`-username`	`string`	Username (with --revoke)

`oa auth passwd`

Flag	Value	Description
`-new-password`	`string`	removed; use --password-stdin
`-old-password`	`string`	removed; use --password-stdin
`-password`	`string`	removed; use --password-stdin
`-password-stdin`	none	Read current then new password from two lines on stdin

`oa auth token create`

Flag	Value	Description
`-kind`	`string`	Token kind: access\|deploy (default "access")
`-name`	`string`	Token name
`-password-stdin`	none	Read the account password from stdin
`-username`	`string`	Account to sign in as (default: the saved token's owner)

Repositories

text

repo list                          List repositories
repo create <name> --format <fmt> [--description D] [--public] [--trash-retention-days N] [--immutable-releases] [--sign-packages]
                                   Create repository
repo show <name>                   Show repository details
repo update <name> [--description D] [--public[=false]] [--trash-retention-days N|default] [--immutable-releases[=false]] [--sign-packages[=false]]
                                   Update repository
repo delete <name> --confirm <name>  Delete repository (moved to the trash; prompts for the name on a terminal)
repo packages <name>               List packages in repository
repo members <name>                List the member repositories of a group repository

Trash

text

trash list [--repo NAME] [--kind K]  List trashed items (all: admin; --repo: repository delete permission)
trash restore <kind> <id> [--repo NAME]  Restore a trashed item or repository
trash purge <kind> <id> [--yes]    Permanently delete a trashed item now (admin)

`oa trash`

text

Usage: oa trash <list|restore|purge>
  oa trash purge <kind> <id> [--yes]            purge one item (admin)
  oa trash purge --repo NAME --all [--yes]      empty a repository's trash (repository manage permission)

`oa trash list`

Flag	Value	Description
`-kind`	`string`	Only items of this kind (e.g. maven_artifact, docker_tag, repository)
`-repo`	`string`	Only items of this repository

`oa trash purge`

Flag	Value	Description
`-all`	none	Purge every trashed item of --repo
`-repo`	`string`	Repository whose trash to empty
`-yes`	none	Do not ask for confirmation

Artifacts

text

artifact list <repo>               List packages in repository
artifact upload <repo> <file>      Upload artifact (auto-detects deb/rpm; files over 5 GiB switch to a multipart presigned upload)
artifact upload --presigned [--path P] [--content-type T] [--multipart] [--part-size SIZE] [--parallel N] <repo> <file>
                                   Upload a raw artifact straight to the object store (presigned PUT; files over 5 GiB,
                                   --multipart or --part-size (128M, 1G or bytes) upload in parts, --parallel 1-16, default 4)
artifact delete <repo> <id>        Delete artifact by ID

`oa artifact upload`

Flag	Value	Description
`-apk-repo`	`string`	Alpine repository directory of an .apk upload (default main)
`-arch`	`string`	Architecture directory of an .apk upload; needed for noarch packages
`-branch`	`string`	Alpine branch directory of an .apk upload (default edge)
`-content-type`	`string`	Content type (--presigned; default: detected by the server)
`-multipart`	none	Upload in parts at any size (--presigned; automatic above 5 GiB)
`-parallel`	`int`	Parts uploaded at the same time, 1 to 16 (--presigned, multipart) (default 4)
`-part-size`	`value`	Part size such as 128M, 1G or a byte count, 5M to 4000M (--presigned; implies --multipart; default: chosen by the server)
`-path`	`string`	Artifact path in the repository (--presigned; default: the file name)
`-presigned`	none	Upload straight to the object store through a presigned URL (raw repositories)

Search

text

search <query> [--repo R] [--fmt F]  Search artifacts

`oa search`

Flag	Value	Description
`-fmt`	`string`	Filter by format
`-limit`	`int`	Max results (default 50)
`-repo`	`string`	Filter by repository

Users (admin)

text

user list                          List users
user create --username U --email E [--password-stdin]  Create user (password prompted without echo)
user show <id>                     Show user
user update <id> [--email E] [--full-name N] [--disabled[=false]]  Update user
user delete <id>                   Delete user

`oa user create`

Flag	Value	Description
`-email`	`string`	Email
`-full-name`	`string`	Full name
`-password`	`string`	removed; use --password-stdin
`-password-stdin`	none	Read the password from stdin
`-username`	`string`	Username

Groups (admin)

text

group list                         List groups
group create <name>                Create group
group show <id>                    Show group
group delete <id>                  Delete group
group members <id>                 List group members
group add-member <id> <user-id>    Add member to group
group rm-member <id> <user-id>     Remove member from group

Projects

text

project list                       List projects
project create <name>              Create a project
project show <name>                Show project (includes my_role)
project update <name> [--display-name N] [--description D]
                                   Update a project (owner); policy flags (--allowed-formats,
                                   --allowed-repo-types, --repo-name-prefix, --allow-public-repos,
                                   --max-repositories, --token-max-ttl-days) need a global admin
project delete <name>              Delete a project
project members <name>             List project members
project add-member <name> (<user-id> | --username U) [--role viewer|developer|maintainer|owner]
                                   Add member to a project
project set-role <name> <user-id> <role>
                                   Change a member's role
project rm-member <name> <user-id> Remove member from project
project groups <name>              List group grants
project add-group <name> <group-id|group-name> [--role viewer|developer|maintainer]
                                   Grant a group access
project rm-group <name> <group-id|group-name>
                                   Remove a group grant

Tokens (admin)

text

token list                         List all tokens
token revoke <id>                  Revoke any token

GPG keys (admin)

text

gpg list                           List GPG keys
gpg import --key <file|-> [--name N] [--passphrase-stdin] [--activate|--no-activate]
                                   Import a private key (passphrase: stdin or env OA_GPG_PASSPHRASE)
gpg generate [--name N] [--algorithm ed25519|rsa4096] [--user-name U] [--email E] [--comment C] [--activate|--no-activate]
                                   Generate a signing key
gpg delete <key> [--force]         Delete a key (id, name or fingerprint)
gpg activate <key> [--repository R]    Make key the signer (global or per deb/rpm repo)
gpg deactivate <key> [--repository R]  Stop using key for signing
gpg export <key> [--output FILE]   Export the public key

`oa gpg import`

Flag	Value	Description
`-activate`	none	Make the key the active signing key
`-key`	`string`	Armored private key file, or - for stdin
`-name`	`string`	Key name
`-no-activate`	none	Do not activate the key
`-passphrase-stdin`	none	Read the key passphrase from stdin (env: OA_GPG_PASSPHRASE)

`oa gpg generate`

Flag	Value	Description
`-activate`	none	Make the key the active signing key
`-algorithm`	`string`	Algorithm: ed25519\|rsa4096 (default "ed25519")
`-comment`	`string`	User ID comment
`-email`	`string`	User ID email
`-name`	`string`	Key name
`-no-activate`	none	Do not activate the key
`-user-name`	`string`	User ID name

`oa gpg delete`

Flag	Value	Description
`-force`	none	Delete even if the key is active or assigned

`oa gpg activate`

Flag	Value	Description
`-repository`	`string`	Repository to activate for (default: global)

`oa gpg deactivate`

Flag	Value	Description
`-repository`	`string`	Repository to deactivate for (default: global)

`oa gpg export`

Flag	Value	Description
`-output`	`string`	Write the public key to FILE (default: stdout)

Storage backends (admin)

text

storage list                       List storage backends
storage create --name N [--type T] [--config-file F|-]
                                   Create storage backend (credentials via --config-file, - = stdin)
storage show <name>                Show storage backend
storage update <name> [--config-file F|-]  Update storage backend
storage delete <name>              Delete storage backend
storage test <name>                Test storage backend

`oa storage create`

Flag	Value	Description
`-config`	`string`	Inline JSON config (non-secret settings only)
`-config-file`	`string`	File with the JSON config, or - for stdin (use this for credentials)
`-name`	`string`	Backend name
`-type`	`string`	Backend type: filesystem\|s3\|gcs\|azure\|garage\|seaweedfs\|oci (default "filesystem")

Backup & restore (admin)

text

backup list                        List backups
backup create [--type full|metadata-only]  Create backup
backup show <id>                   Show backup
backup download <id> <dest>        Download backup
backup restore <archive-file>      Restore from a downloaded backup archive

`oa backup create`

Flag	Value	Description
`-type`	`string`	Backup type: full\|metadata-only (default "full")

Audit log (admin)

text

audit list [--limit N] [--action A] [--actor A]  List audit entries
audit export [--format jsonl|csv] [--since T] [--until T] [--actor A] [--action A] [-o FILE]
                                   Export the audit log (default: jsonl to stdout)

`oa audit list`

Flag	Value	Description
`-action`	`string`	Filter by action
`-actor`	`string`	Filter by actor
`-limit`	`int`	Max entries (default 50)

`oa audit export`

Flag	Value	Description
`-action`	`string`	Filter by action
`-actor`	`string`	Filter by actor
`-format`	`string`	Export format: jsonl\|csv (default "jsonl")
`-o`	`string`	Write to this file instead of stdout
`-output`	`string`	Write to this file instead of stdout
`-since`	`string`	Only entries at or after this time (RFC 3339, YYYY-MM-DD or an age like 24h, 7d)
`-until`	`string`	Only entries before this time (same forms)

Webhooks

text

webhook list                       List global webhooks
webhook create --name N --url U --events E,E [--secret-file F] [--active=false]  Create webhook
webhook show <id>                  Show webhook
webhook update <id> [--name N] [--url U] [--events E,E] [--active[=false]]  Update webhook
webhook delete <id>                Delete webhook
webhook test <id>                  Test webhook
webhook deliveries <id>            List webhook deliveries
webhook repo list <repo>           List repo webhooks
webhook repo create <repo> --name N --url U --events E,E [--secret-file F]  Create repo webhook

`oa webhook create`

Flag	Value	Description
`-active`	none	Enabled (default true)
`-events`	`string`	Comma-separated event types, e.g. artifact.uploaded (required)
`-name`	`string`	Webhook name
`-secret`	`string`	removed; use --secret-file
`-secret-file`	`string`	file holding the webhook secret, '-' for stdin (or OA_WEBHOOK_SECRET)
`-url`	`string`	Webhook URL

SBOM

text

sbom list <repo>                   List SBOMs for repository
sbom generate <repo> --artifact-id ID [--format cyclonedx|spdx|spdx-json|spdx3-json] [--spec-version V]
                                   Generate an SBOM for one artifact (CycloneDX 1.4-1.6, SPDX 2.3)
sbom show <repo> <id>              Show SBOM
sbom download <repo> <id> <dest> [--attest true|bundle]   Download SBOM (or its signed attestation)
sbom delete <repo> <id>            Delete SBOM
vex get <repo> [--artifact-id ID] [--format openvex|cyclonedx] [--spec-version V] [--output FILE] [--attest true|bundle]
                                   VEX document of an artifact or the whole repository (stdout without --output)
vex list <repo> [--artifact-id ID] List recorded VEX decisions
vex set <repo> --artifact-id ID --vuln CVE --status S [--justification J] [--impact TEXT] [--action TEXT]
                                   Record a VEX decision (not_affected requires --justification)
vex delete <repo> <id>             Delete a VEX decision
dtrack show|test|pushes <repo>     Dependency-Track integration of a repository
dtrack push <repo> --artifact-id ID   Push an artifact to Dependency-Track

Vulnerability scanning

text

vuln scan <repo> --artifact-id ID --package P --version V --ecosystem E [--scanner osv|trivy|grype]
                                   Scan one package for vulnerabilities
vuln list <repo>                   List vulnerability scans
vuln show <repo> <id>              Show vulnerability scan
vuln quarantine <repo> <id>        Quarantine vulnerable package
vuln delete <repo> <id>            Delete vulnerability scan

License scanning

text

license scan <repo> --artifact-id ID  Scan one artifact for license issues
license list <repo>                List license scans
license show <repo> <id>           Show license scan

Secret scanning

text

secret scan <repo> --artifact-id ID [--content-file F|-]  Scan one artifact (and optional content) for secrets
secret list <repo>                 List secret scans
secret show <repo> <id>            Show secret scan
secret quarantine <repo> <id>      Quarantine secret
secret delete <repo> <id>          Delete secret scan

Cleanup policies

text

cleanup list <repo>                List cleanup policies
cleanup create <repo> --name N [--keep-count N] [--keep-days N] [--name-pattern RE] [--schedule CRON] [--enabled=false]
                                   Create cleanup policy (needs --keep-count or --keep-days)
cleanup show <repo> <id>           Show cleanup policy
cleanup update <repo> <id> [same flags]  Update cleanup policy
cleanup delete <repo> <id>         Delete cleanup policy
cleanup run <repo> <id>            Run cleanup policy now

Storage quotas

text

quota show <repo>                  Show repository quota
quota set <repo> [--limit N --unit MB|GB|TB] [--max-artifacts N] [--warn-percent P]  Set quota
quota delete <repo>                Remove quota

Artifact properties

text

props list <repo> <artifact-id>    List artifact properties
props set <repo> <artifact-id> <key> <value>  Set property
props delete <repo> <artifact-id> <key>       Delete property
props search <repo> <key> <value>  Search artifacts by property

CI (see docs/integrations/ci.md)

text

upload <repo> <file|glob>... [--target-path P] [--flat] [--property k=v]... [--build-name N] [--build-number M] [--build-url U] [--vcs-revision SHA]
                                   Upload files to a raw/maven/ivy/sbt/deb/rpm repository and set build properties
bundle create <name> <version> [--description D] [--pipeline P]
                                   Create a draft release bundle
bundle add <name> <version> --repo R --path P... | --from-build NAME/NUMBER [--repo R]...
                                   Add artifacts to a draft bundle, by path or by the build that produced them
bundle seal <name> <version> [--gpg-key K]  Seal a bundle (optionally sign its manifest)
bundle show <name> <version>       Show a bundle and its items
promote <name> <version> --stage S [--target-repo R] [--notes T]
                                   Promote a sealed bundle to a pipeline stage

`oa upload`

Flag	Value	Description
`-build-name`	`string`	Build name, recorded as property build.name
`-build-number`	`string`	Build number, recorded as property build.number
`-build-url`	`string`	Build URL, recorded as property build.url
`-flat`	none	Drop the local directories: upload every file by its name
`-property`	`value`	Property k=v set on every uploaded artifact (repeatable)
`-target-path`	`string`	Path in the repository; a trailing / makes it a directory (default: the file's path)
`-vcs-revision`	`string`	Source revision, recorded as property vcs.revision

`oa bundle`

text

Usage: oa bundle <create|add|seal|show> <name> <version> [flags]
  oa bundle create <name> <version> [--description D] [--pipeline P]
  oa bundle add <name> <version> --repo R --path P... | --from-build NAME/NUMBER [--repo R]...
  oa bundle seal <name> <version> [--gpg-key K]
  oa bundle show <name> <version>

`oa bundle create`

Flag	Value	Description
`-description`	`string`	Bundle description
`-pipeline`	`string`	Promotion pipeline, by name (needed to promote the bundle later)

`oa bundle add`

Flag	Value	Description
`-from-build`	`string`	Add every artifact recorded for build NAME/NUMBER (properties build.name and build.number)
`-path`	`value`	Artifact path in --repo (repeatable)
`-repo`	`value`	Repository of the artifacts (repeatable with --from-build to limit the search)

`oa bundle seal`

Flag	Value	Description
`-gpg-key`	`string`	Sign the manifest with this GPG key (id as the server lists it)

`oa bundle show`

text

Usage of bundle show:

`oa promote`

Flag	Value	Description
`-notes`	`string`	Promotion notes
`-stage`	`string`	Pipeline stage to promote to (required)
`-target-repo`	`string`	Repository to promote into (default: the one the stage fixes)

Migration

text

import nexus|artifactory --source-url URL --repo SRC[:DST]... [--dry-run] [--create-repos]
                                   [--concurrency N] [--state-file F]  Import from Nexus / Artifactory

`oa import nexus`

Flag	Value	Description
`-artifactory-listing`	`string`	Artifactory listing mode: aql or storage (default "aql")
`-concurrency`	`int`	parallel transfers (default 4)
`-create-repos`	none	create missing destination repositories (hosted, matching format)
`-deb-component`	`string`	fallback Debian component when the source does not say
`-deb-distribution`	`string`	fallback Debian distribution when the source does not say
`-dry-run`	none	print the plan without writing anything
`-path-prefix`	`string`	only import assets whose repository path starts with this prefix (e.g. com/acme/)
`-properties`	`string`	properties to copy: comma-separated keys or prefix* patterns, 'none' to disable (default "deb.,rpm.,build.name,build.number,vcs.*")
`-quiet`	none	only print the summary
`-repo`	`value`	repository to import as SRC or SRC:DST (repeatable)
`-retries`	`int`	retries after a transient failure of a source request or an upload (0 disables) (default 3)
`-retry-max-wait`	`duration`	longest wait between retries; a Retry-After above it is not waited out (default 30s)
`-source-token-file`	`string`	file holding the source token/password, '-' for stdin (or OA_IMPORT_SOURCE_TOKEN)
`-source-url`	`string`	base URL of the source system
`-source-user`	`string`	source user name (or OA_IMPORT_SOURCE_USER)
`-state-file`	`string`	resume file: completed assets are skipped on the next run

`oa import artifactory`

Same flags as oa import nexus.

Declarative configuration (admin)

text

apply -f FILE|DIR|- [-R] [--kind K] [--prune|--prune-all] [--force-secrets] [--continue-on-error] [--validate-only] [-o json]
                                   Make the server match the YAML manifests
diff  -f FILE|DIR|- [-R] [--kind K] [--prune|--prune-all] [-o json]
                                   Show what apply would change (exit 0 none, 2 changes, 1 error)
export [--kind K] [--with-members] [-o DIR]
                                   Write the current configuration as manifests

`oa apply`

Flag	Value	Description
`-R`	none	Descend into subdirectories of -f directories
`-continue-on-error`	none	Keep applying after a failure (exit status is still 1)
`-f`	`value`	Manifest file, directory or - for stdin (repeatable)
`-force-secrets`	none	Send every secret even if the server reports it as set
`-kind`	`value`	Only consider this kind (repeatable), e.g. Repository
`-o`	`string`	Output format: json (default: human readable)
`-prune`	none	Delete objects previously applied by oa that are no longer in the manifests
`-prune-all`	none	Delete every object absent from the manifests, managed or not (never seeded objects; Users only with --kind User)
`-validate-only`	none	Validate the manifests offline and exit

`oa diff`

Flag	Value	Description
`-R`	none	Descend into subdirectories of -f directories
`-f`	`value`	Manifest file, directory or - for stdin (repeatable)
`-force-secrets`	none	Send every secret even if the server reports it as set
`-kind`	`value`	Only consider this kind (repeatable), e.g. Repository
`-o`	`string`	Output format: json (default: human readable)
`-prune`	none	Delete objects previously applied by oa that are no longer in the manifests
`-prune-all`	none	Delete every object absent from the manifests, managed or not (never seeded objects; Users only with --kind User)

`oa export`

Flag	Value	Description
`-kind`	`value`	Only export this kind (repeatable); User is exported only when named
`-o`	`string`	Write one file per object into this directory (default: one YAML stream on stdout)
`-with-members`	none	Include fields normally omitted, such as Group members

Package deltas

text

delta list <repo> <pkg-id>         List available deltas for package
delta get <repo> <pkg-id> --from <sha256> <dest>  Download delta patch

System

text

system info                        Show system information

Utility

text

version                            Show CLI version (--format json for machine use)
help                               Show this help

CLI reference ​

Usage ​

Global flags ​

Environment variables ​

Auth ​

oa auth login ​

oa auth logout ​

oa auth passwd ​

oa auth token create ​

Repositories ​

Trash ​

oa trash ​

oa trash list ​

oa trash purge ​

Artifacts ​

oa artifact upload ​

Search ​

oa search ​

Users (admin) ​

oa user create ​

Groups (admin) ​

Projects ​

Tokens (admin) ​

GPG keys (admin) ​

oa gpg import ​

oa gpg generate ​

oa gpg delete ​

oa gpg activate ​

oa gpg deactivate ​

oa gpg export ​

Storage backends (admin) ​

oa storage create ​

Backup & restore (admin) ​

oa backup create ​

Audit log (admin) ​

oa audit list ​

oa audit export ​

Webhooks ​

oa webhook create ​

SBOM ​

Vulnerability scanning ​

License scanning ​

Secret scanning ​

Cleanup policies ​

Storage quotas ​

Artifact properties ​

CI (see docs/integrations/ci.md) ​

oa upload ​

oa bundle ​

oa bundle create ​

oa bundle add ​

oa bundle seal ​

oa bundle show ​

oa promote ​

Migration ​

oa import nexus ​

oa import artifactory ​

Declarative configuration (admin) ​

oa apply ​

oa diff ​

oa export ​

Package deltas ​

System ​

Utility ​

CLI reference

Usage

Global flags

Environment variables

Auth

`oa auth login`

`oa auth logout`

`oa auth passwd`

`oa auth token create`

Repositories

Trash

`oa trash`

`oa trash list`

`oa trash purge`

Artifacts

`oa artifact upload`

Search

`oa search`

Users (admin)

`oa user create`

Groups (admin)

Projects

Tokens (admin)

GPG keys (admin)

`oa gpg import`

`oa gpg generate`

`oa gpg delete`

`oa gpg activate`

`oa gpg deactivate`

`oa gpg export`

Storage backends (admin)

`oa storage create`

Backup & restore (admin)

`oa backup create`

Audit log (admin)

`oa audit list`

`oa audit export`

Webhooks

`oa webhook create`

SBOM

Vulnerability scanning

License scanning

Secret scanning

Cleanup policies

Storage quotas

Artifact properties

CI (see docs/integrations/ci.md)

`oa upload`

`oa bundle`

`oa bundle create`

`oa bundle add`

`oa bundle seal`

`oa bundle show`

`oa promote`

Migration

`oa import nexus`

`oa import artifactory`

Declarative configuration (admin)

`oa apply`

`oa diff`

`oa export`

Package deltas

System

Utility