Artifact Access Management with Apheris CLI

This guide shows you how to use the Apheris CLI to manage access to your artifacts, allowing you to share computational outputs with specific users or organizations.

Prerequisites

• Apheris CLI installed and configured
• Authenticated with apheris login (Auth0)
• Artifacts created by your organization (generated during computations)

Permissions

Only artifact creators and organization admins can manage access. See Who Can Share Artifacts? for details.

Listing Your Shareable Artifacts

To see all artifacts your organization can share:

apheris artifacts list

Example output:

+---+----------------------------------------+---------------------------+------------+------------------+-------------------------+
|  idx  | artifact_id                            | name                      | type       | createdBy        | createdAt               |
+---+----------------------------------------+---------------------------+------------+------------------+-------------------------+
| 0 | c0fd87ef-20ee-430f-ab33-3369bac2cf97   | model-checkpoint-epoch-10 | checkpoint | jane@example.com | 2024-01-15T10:30:00Z    |
| 1 | d1a2b3c4-5e6f-7890-a1b2-c3d4e5f6a7b8   | training-metrics          | metric     | john@example.com | 2024-01-14T15:45:00Z    |
| 2 | a1b2c3d4-e5f6-7890-1234-567890abcdef   | final-model-results       | result     | jane@example.com | 2024-01-13T09:00:00Z    |
+---+----------------------------------------+---------------------------+------------+------------------+-------------------------+

Filter by Artifact Type

To list only specific types of artifacts:

# List only checkpoints
apheris artifacts list --type checkpoint

# List only metrics
apheris artifacts list --type metric

# List only logs
apheris artifacts list --type log

# List only results
apheris artifacts list --type result

Limit Results

Control the number of artifacts returned:

# Return 50 artifacts (default is 20)
apheris artifacts list --page-size 50

# Return only 10 artifacts
apheris artifacts list -s 10

Granting Access to Artifacts

You can grant access to an artifact by email or organization ID. Only one recipient can be specified per grant.

Grant Access by Email

Grant access to a specific user by their email address:

apheris artifacts grant \
  --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  --email collaborator@partner.com

Shorthand:

apheris artifacts grant \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -e collaborator@partner.com

Success output:

Access granted to collaborator@partner.com. Access grant ID: f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0

Grant Access by Organization

Grant access to all users in a specific organization:

apheris artifacts grant \
  --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  --org-id org_abc123xyz

Shorthand:

apheris artifacts grant \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -o org_abc123xyz

To find organization IDs:

apheris orgs list

Common Scenarios

Share a model checkpoint with a collaborator

# List your checkpoints
apheris artifacts list --type checkpoint

# Grant access to collaborator
apheris artifacts grant \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -e data.scientist@partner-org.com

Share metrics with your partner organization

# List your metrics
apheris artifacts list --type metric

# Get partner organization ID
apheris orgs list

# Grant org-wide access
apheris artifacts grant \
  -i d1a2b3c4-5e6f-7890-a1b2-c3d4e5f6a7b8 \
  -o org_partner123

Viewing Access Grants

To see who has access to a specific artifact:

apheris artifacts list --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97

Shorthand:

apheris artifacts list -i c0fd87ef-20ee-430f-ab33-3369bac2cf97

Example output:

+---+----------------------------------------+----------------------------+----------------+-------------------------+
|  idx  | access_id                              | recipientEmail             | recipientOrgID | createdAt               |
+---+----------------------------------------+----------------------------+----------------+-------------------------+
| 0 | f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0   | collaborator@partner.com   | None           | 2024-01-15T11:00:00Z    |
| 1 | a1b2c3d4-e5f6-7890-1234-567890abcdef   | None                       | org_partner123 | 2024-01-15T12:30:00Z    |
+---+----------------------------------------+----------------------------+----------------+-------------------------+

Revoking Access

To revoke access, you need both the artifact ID and the access grant ID:

apheris artifacts revoke \
  --artifact-id c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  --access-id f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0

Shorthand:

apheris artifacts revoke \
  -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
  -a f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0

Revoke Workflow

1. List access grants for an artifact:

   apheris artifacts list -i c0fd87ef-20ee-430f-ab33-3369bac2cf97
   

2. Copy the access_id you want to revoke

3. Revoke the access:

   apheris artifacts revoke \
     -i c0fd87ef-20ee-430f-ab33-3369bac2cf97 \
     -a f3g4h5i6-j7k8-9012-l3m4-n5o6p7q8r9s0
   

Uploading Artifacts

In addition to artifacts generated during computations, you can create an artifact and upload local files to it directly from the CLI. This is useful for sharing models, metrics, or results that were produced outside of an Apheris computation.

This command requires Apheris CLI version 0.60.0 or later.

Uploaded artifacts are not private data

Uploading an artifact is different from registering a dataset in the Governance Portal. Apheris hosts the artifact store, so uploaded files are accessible to Apheris — unlike datasets registered in the Governance Portal, which never leave the Data Custodian's environment. Do not upload private or sensitive data as an artifact.

To create an artifact and upload a single file:

apheris artifacts upload \
  --name my-model-checkpoint \
  --type checkpoint \
  --file ./model.pt

Shorthand:

apheris artifacts upload \
  -n my-model-checkpoint \
  -t checkpoint \
  -f ./model.pt

The --type must be one of checkpoint, metric, log, or result. If an artifact with the same name already exists within your organization, it is reused and the files are added to it. Reusing an existing artifact does not update its type, metadata, model ID, or model version.

While each file is transferred, the CLI reports upload progress:

Uploading... 100% (1048576/1048576 bytes)

Success output:

Artifact upload complete: created artifact c0fd87ef-20ee-430f-ab33-3369bac2cf97, file model.pt uploaded.

Upload Multiple Files

Repeat the --file option to upload several files to the same artifact. Each file is stored under its local file name, so files in different directories must not have the same name in one upload command.

apheris artifacts upload \
  --name training-run-42 \
  --type result \
  --file ./predictions.csv \
  --file ./metrics.json \
  --file ./run.log

Success output:

Artifact upload complete: created artifact d1a2b3c4-5e6f-7890-a1b2-c3d4e5f6a7b8, 3 files uploaded.
- predictions.csv uploaded
- metrics.json uploaded
- run.log uploaded

Set a File Key

For a single-file upload, use --key to control the file name stored inside the artifact. If omitted, the local file name is used. Nested paths are not supported, and --key cannot be used when uploading multiple files.

apheris artifacts upload \
  -n my-model-checkpoint \
  -t checkpoint \
  -f ./epoch_10.pt \
  --key model.pt

Attach Metadata

Provide optional metadata as a JSON object with --metadata:

apheris artifacts upload \
  -n training-metrics \
  -t metric \
  -f ./metrics.json \
  --metadata '{"experiment": "baseline", "epochs": 10}'

Associate with a Model

Link the artifact to a model in the Registry by providing both --model-id and --model-version:

apheris artifacts upload \
  -n my-model-checkpoint \
  -t checkpoint \
  -f ./model.pt \
  --model-id apheris-xgboost \
  --model-version 1.0.0

Once uploaded, you can share the artifact with the grant command, just like any computation-generated artifact.

If a multi-file upload fails part way through, files that completed before the failure remain attached to the artifact. When retrying multiple files, the stored file key is each local file's basename, so retry only files whose basenames are not already present on the artifact.

Error Handling

Common Errors

Artifact not found:

Artifact not found.

• Verify the artifact ID is correct
• Ensure the artifact belongs to your organization

Duplicate grant:

An access grant for this recipient already exists.

• The user or organization already has access
• Check existing grants with apheris artifacts list -i <artifact-id>

Authorization failed:

You are not authorized. Please log in or check your permissions.

• See Who Can Share Artifacts? for permission details

Invalid parameters:

Specify exactly one of --email or --org-id.

• You must provide either --email or --org-id, but not both
• Use --email for individual users or --org-id for organizations

No file provided:

At least one --file must be provided.

• Provide at least one --file, and repeat the option to upload multiple files

Invalid metadata:

--metadata must be a JSON object.

• --metadata must be a valid JSON object, for example '{"key": "value"}'

Incomplete model reference:

Specify both --model-id and --model-version, or omit both options.

• To associate an artifact with a model, provide both --model-id and --model-version

File already exists:

Artifact file already exists or the upload is still in progress.

• A file with the same key was already uploaded, or a previous upload has not finished

Invalid file key:

file_key must be a flat file name without path separators.

• Use --key only with a single file
• Do not include / or \ in the key
• In multi-file uploads, make sure each local file name is unique

Best Practices

1. Use organization grants for teams: When sharing with a partner organization, use --org-id to grant access to all their users

2. Use email grants for individuals: When collaborating with specific people, use --email for granular control

3. Regularly audit access: Periodically review who has access to your artifacts:

   apheris artifacts list -i <artifact-id>
   

4. Revoke when no longer needed: Clean up access grants when collaborations end

5. Document sharing decisions: Keep records of why access was granted, especially for compliance

Related Documentation

• Artifacts Overview
• Accessing Shared Artifacts in the Portal
• Artifacts API Reference
• CLI Reference