permanence-cli

permanence-cli is a command-line tool for uploading and downloading files with Permanence.

1. Install

yarn global add permanence-cli
# or
npm install -g permanence-cli

This gives you the permanence command.

2. Configure (optional for defaults)

Out of the box, the CLI is preconfigured to talk to a public Sonic testnet:

• RPC URL (default): https://rpc.testnet.soniclabs.com
• Contract address (default): 0x4cBe7963b92ceFCc0C77d68EB7Aa0C663E21e736

You mainly need to provide a wallet private key so the CLI can pay for uploads.
You can either export SONIC_PRIVATE_KEY in your shell or run the config command:

permanence config

The config command lets you override any of the presets:

• --rpc-url – RPC endpoint for the chain you're using (optional – defaults above)
• --contract – ChunkStorage contract address (optional – default above)
• --private-key – wallet private key used to pay for storage

Configuration Storage:

The CLI uses a two-tier configuration system:

1. Global Config (system-wide):

   • Linux/macOS: ~/.config/permanence/config.json
   • Windows: %APPDATA%/permanence/config.json
   • Used from any directory - configure once, use everywhere

2. Local Config (project-specific override):

   • .permanence file in your current working directory
   • Takes precedence over global config
   • Useful for project-specific settings or development

Config Priority: Local > Global > Defaults

When you run permanence config, it saves to the global location by default. If a .permanence file exists in your current directory, it will save there instead (for dev/custom purposes).

3. Commands

All commands assume you’ve run permanence config at least once.

• Upload a file (no encryption)

  permanence upload <path-to-file>

  Prints a content ID you can store and share.

• Upload a file with encryption

  You can encrypt files in two ways:

  • Wallet-key encryption (default when you request encryption without a password):

    permanence upload <path-to-file> --encrypt
    # or (alias)
    permanence upload <path-to-file> --encrypted

    In this mode, the CLI derives a secret from your configured wallet private key and uses that as the encryption password.
    There is no extra password to remember: only the same wallet key can decrypt the content.

  • Password-based encryption (shareable secret):

    # Prompt for a password (and use it for encryption)
    permanence upload <path-to-file> --password
    
    # Or pass the password inline
    permanence upload <path-to-file> --encrypt --password "my-strong-password"

    Any time you provide --password <value>, that password is used directly for encryption, and encryption is enabled even if you omit --encrypt.

• Download a file

  permanence download <content-id> -o <output-path>

  Reconstructs the original file at output-path.

  • If the file was encrypted with your wallet key, and your CLI is configured with the same private key, decryption will be attempted automatically (no prompt).
  • If the file was encrypted with a password, or the wallet-based attempt fails, the CLI will:
    • use --password <value> if you provided it, or
    • prompt: Enter decryption password: and then retry with that value.

• Check balance / usage

  permanence balance

  Shows the wallet/contract balance and basic usage information.

• View help

  permanence --help
  permanence <command> --help