Sidebar navigationMain contentFooter
HomeLabsIPFS NamingAPI/CLI
Name operations
Jump toUpdate content

Created by Protocol Labs, InterPlanetary File System (IPFS) is a decentralized protocol used to store and share content.

Scaleway IPFS Naming allows you to create a key to point to your latest update, and above all maintain this information on the IPFS network and share it through Distributed Hash Tables (DHTs), giving you an extra layer of performance in the region of your choice. This way your records remain available and accessible, even when your local machine is offline.

In this quickstart, we will show you how to create and import an IPNS key and update your records using Scaleway IPFS Naming.

Scaleway Command Line Interface overview

The Scaleway Command Line Interface (CLI) allows you to create and interact with your names. You will be able to create names, manage them, and add/delete value within them.

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

  • you are the Owner of the Scaleway Organization in which the actions will be carried out, or
  • you are an IAM user of the Organization, with a policy granting you the necessary permission sets
Requirements:

Configuring the CLI

  1. Open a terminal and enter the following command, to configure the Scaleway CLI on your machine:

    scw init

    If you have already configured the CLI, you will see a message like the following:

    Current config is located at /path/to/config.yaml
    access_key: <YOUR ACCESS KEY>
    secret_key: <YOUR SECRET KEY>
    default_organization_id: <YOUR ORGANIZATION ID>
    default_project_id: <YOUR PROJECT ID>
    default_region: <YOUR DEFAULT REGION, eg fr-par>
    default_zone: <YOUR DEFAULT ZONE, eg fr-par-1>
    Do you want to override the current config? (Y/n):
    Note:

    As the project is available on pl-waw, nl-ams and fr-par, you can set the region to pl-waw, nl-ams or fr-par.

  2. Unless you want to change your configuration, you can type n and go directly to the Creating a Name step of this tutorial. If you have not yet configured the CLI, you will be guided through the configuration process via a series of questions:

    Enter a valid secret-key or an email

  3. Enter either the email address for your account (you will then be asked for your password), or your API secret key:

    To improve this tool we rely on diagnostic and usage data.
    Sending such data is optional and can be disabled at any time by running "scw config set send-telemetry=false".
    Do you want to send usage statistics and diagnostics? (Y/n):

    Type y or n and hit enter.

    To fully enjoy Scaleway CLI we recommend you install autocomplete support in your shell.
    Do you want to install autocomplete? (Y/n):

    Type y or n and hit enter.

    To enable autocomplete, scw needs to update your shell configuration.
    What type of shell are you using (default: zsh):

  4. Hit enter if the default shell type is already correct for you. Otherwise, enter your shell type and hit enter.

    To enable autocomplete we need to append to /Users/yourusername/.zshrc the following lines:
    # Scaleway CLI autocomplete initialization.
    eval "$(scw autocomplete script shell=zsh)"
    Do you want to proceed with these changes? (Y/n):

    Type y or n and hit enter. This should complete the configuration process:

     Initialization completed with success.

Creating a name

This operation creates a new key. A key, which will be associated with a value to create record.

Type the following command to create your key using the CLI.

scw ipns name create name=my-website value=QmULjVfvvMf3v637XLQuBoYqchFC5MCPYLJmVeTMVcACK2

You should get a response like the following, providing details about your newly created name.

NameID $NAME_ID
ProjectID 00000000-0000-0000-0000-000000000000
Region fr-par
Key -
CreatedAt now
UpdatedAt now
Name my-website
Status queued
Value QmULjVfvvMf3v637XLQuBoYqchFC5MCPYLJmVeTMVcACK2

Alternatively, you can also run the following API command. Make sure to replace the values with your own, using the API configuration table below.

curl -X POST \
 -H "X-Auth-Token: $SECRET_KEY" \
 -H "Content-Type: application/json" \
 "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/names" \
 -d '{
   "project_id": "$PROJECT_ID",
   "name": "my-website",
   "value": "QmULjVfvvMf3v637XLQuBoYqchFC5MCPYLJmVeTMVcACK2"
 }'
ParameterDescription
$SECRET_KEYThe secret part of your API key
$REGION_IDCreate a name in this given region. Possible values are fr-par, pl-waw and nl-ams. Default value is fr-par.
$PROJECT_IDID of the Project you want to create your key in. Your Project name can only contain alphanumeric characters, spaces, dots, and dashes. To find your Project ID, you can consult the Scaleway console
nameCreate a key with this given name.
valueAssign specific value to your records.

Import a key

This operation allows you to import an existing key.

Run the following command to import an existing key using the CLI:

scw ipns name import-key name=import-name-key value=QmULjVfvvMf3v637XLQuBoYqchFC5MCPYLJmVeTMVcACK2 private-key=$PRIVATE_KEY_BASE64
Tip:

To export your key from your Kubo client in base64, follow these instructions in export key section.

You should get a response like the following, providing details about the name.

tags []
NameID $NAME_ID
ProjectID $PROJECT_ID
CreatedAt now
UpdatedAt now
Name import-name-key
Key -
Status Queued
Value QmULjVfvvMf3v637XLQuBoYqchFC5MCPYLJmVeTMVcACK2
Region fr-par

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below.

curl -X POST \
 -H "X-Auth-Token: $SECRET_KEY" \
 -H "Content-Type: application/json" \
 "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/names/import-key" \
 -d '{
   "project_id": "$PROJECT_ID",
   "name": "my-website",
   "value": "QmULjVfvvMf3v637XLQuBoYqchFC5MCPYLJmVeTMVcACK2",
   "private-key": "$PRIVATE_KEY_BASE64"
 }'

Export a key

This operation allows you to export an existing key.

Run the following command to export an existing key using the CLI:

scw ipns name export-key name-id=$NAME_ID

You should get a response like the following, providing details about the name.

NameID $NAME_ID
ProjectID $PROJECT_ID
CreatedAt now
UpdatedAt now
PublicKey $PUBLIC_KEY
PrivateKey $PRIVATE_KEY_BASE64
Tip:

To import your key into your Kubo client, follow these instructions in import key section.

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below.

curl -X GET \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/names/<NAME-ID>/export-key"

Deleting a name

This operation allows you to delete a given name.

Run the following command to delete your name using the CLI. Just make sure to replace the name-id value with your own.

scw ipns name delete name-id=11111111-1111-1111-1111-111111111111
Note:

If the operation is successful, no output will be returned.

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below.

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SECRET_KEY" \
  "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/name/<NAME-ID>"

Retrieving information about a name

This operation allows you to retrieve information about a given name.

Run the following command to retrieve information about your name using the CLI:

scw ipns name get name-id=11111111-1111-1111-1111-111111111111

You should get a response like the following, providing details about the name.

NameID $NAME_ID
ProjectID $PROJECT_ID
CreatedAt now
UpdatedAt now
Name my-website
Key $KEY
Status published
Value QmULjVfvvMf3v637XLQuBoYqchFC5MCPYLJmVeTMVcACK2

Alternatively, you can also run the following API command. Make sure you replace the example values with your own, using the API configuration table below.

curl -X GET \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/names/<NAME-ID>"

Listing names

This operation allows you to list all names from a given Project.

Run the following command to list all names from a Project using the CLI:

scw ipns name list

You should get a response like the following, providing a list of all names contained within a Project.

ID                                    PROJECT ID
11111111-1111-1111-1111-111111111111  00000000-0000-0000-0000-000000000000
22222222-2222-2222-2222-222222222222  00000000-0000-0000-0000-000000000000

Alternatively, you can also run the following API command:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/names?order_by=created_at_asc&project_id=$PROJECT_ID"

Update a name

This operation allows you to update the details of a given name, specified by its name and/or tag and/or value.

Run the following CLI command to update:

scw ipns name update name-id=$NAME_ID name=new-name-website value=QmYyKBtEFXnxBQNzi9VyHwtdTSRSgQihCmkBuFNWcnQiBs

You should get an output similar to the following one, showing you your updates:

NameID $NAME_ID
ProjectID $PROJECT_ID
Status published
CreatedAt 22 minutes ago
UpdatedAt now
Name new-name-website
Key $KEY
Value QmYyKBtEFXnxBQNzi9VyHwtdTSRSgQihCmkBuFNWcnQiBs

Alternatively, you can also run the following API command. Just make sure to replace the example values with your own, using the API configuration table below:

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $SCW_SECRET_KEY" \
  "https://api.scaleway.com/ipfs/v1alpha1/regions/$REGION_ID/names/<NAME-ID>" \
  -d '{
  "name": "my-updated-name",
  "tags": [
    "my-tag"
  ],
  "value": "QmYyKBtEFXnxBQNzi9VyHwtdTSRSgQihCmkBuFNWcnQiBs"
}'
ParameterDescription
$SECRET_KEYThe secret part of your API key
$REGION_IDCreate a name in this given region. Possible values are fr-par, pl-waw and nl-ams. Default value is fr-par.
$PROJECT_IDID of the Project you want to create your key in. Your Project name can only contain alphanumeric characters, spaces, dots, and dashes. To find your Project ID, you can consult the Scaleway console
nameCreate a key with this given name.
valueAssign specific value to your records.