package module
v0.7.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Aug 22, 2023 License: MIT Imports: 26 Imported by: 536



standard-readme compliant GoDoc Build Status

The go interface to ipfs's HTTP API


go install

This will download the source into $GOPATH/src/


See the godocs for details on available methods. This should match the specs at ipfs/specs (Core API); however, there are still some methods which are not accounted for. If you would like to add any of them, see the contribute section below. See also the HTTP API.


Add a file with the contents "hello world!":

package main

import (

    	shell ""

func main() {
	// Where your local node is running on localhost:5001
	sh := shell.NewShell("localhost:5001")
	cid, err := sh.Add(strings.NewReader("hello world!"))
	if err != nil {
        fmt.Fprintf(os.Stderr, "error: %s", err)
    fmt.Printf("added %s", cid)

For a more complete example, please see:


Contributions are welcome! Please check out the issues.

Want to hack on IPFS?





package shell implements a remote API interface for a running ipfs daemon



View Source
const (
	DefaultPathName = ".ipfs"
	DefaultPathRoot = "~/" + DefaultPathName
	DefaultApiFile  = "api"
	EnvDir          = "IPFS_PATH"
View Source
const (
	TRaw = iota


View Source
var (
	FilesLs    filesLs
	FilesChcid filesChcid
	FilesMkdir filesMkdir
	FilesRead  filesRead
	FilesWrite filesWrite
	FilesStat  filesStat
	FilesCp    filesCp
View Source
var KeyGen keyGen
View Source
var KeyImportGen keyImportOpt


This section is empty.


type AddOpts

type AddOpts = func(*RequestBuilder) error

func CidVersion added in v0.0.2

func CidVersion(version int) AddOpts

CidVersion allows for selecting the CID version that ipfs should use.

func Hash added in v0.0.2

func Hash(hash string) AddOpts

Hash allows for selecting the multihash type

func OnlyHash

func OnlyHash(enabled bool) AddOpts

func Pin

func Pin(enabled bool) AddOpts

func Progress

func Progress(enabled bool) AddOpts

func RawLeaves

func RawLeaves(enabled bool) AddOpts

type DagImportOutput added in v0.5.0

type DagImportOutput struct {
	Roots []DagImportRoot
	Stats *DagImportStats

type DagImportRoot added in v0.5.0

type DagImportRoot struct {
	Root struct {
		Cid struct {
			Value string `json:"/"`
	Stats *DagImportStats `json:"Stats,omitempty"`

type DagImportStats added in v0.5.0

type DagImportStats struct {
	BlockBytesCount uint64
	BlockCount      uint64

type DagPutOutput added in v0.5.0

type DagPutOutput struct {
	Cid struct {
		Target string `json:"/"`

type Error

type Error struct {
	Command string
	Message string
	Code    int

func (*Error) Error

func (e *Error) Error() string

type FilesOpt added in v0.1.0

type FilesOpt func(*RequestBuilder) error

type FilesStatObject added in v0.1.0

type FilesStatObject struct {
	Blocks         int
	CumulativeSize uint64
	Hash           string
	Local          bool
	Size           uint64
	SizeLocal      uint64
	Type           string
	WithLocality   bool

type IdOutput

type IdOutput struct {
	ID              string
	PublicKey       string
	Addresses       []string
	AgentVersion    string
	ProtocolVersion string

type IpfsObject

type IpfsObject struct {
	Links []ObjectLink
	Data  string

type Key added in v0.2.0

type Key struct {
	Id   string
	Name string

type KeyImportOpt added in v0.4.0

type KeyImportOpt func(*RequestBuilder) error

type KeyOpt added in v0.2.0

type KeyOpt func(*RequestBuilder) error

type KeyRenameObject added in v0.2.0

type KeyRenameObject struct {
	Id        string
	Now       string
	Overwrite bool
	Was       string
type LsLink struct {
	Hash string
	Name string
	Size uint64
	Type int

type LsObject

type LsObject struct {
	Links []*LsLink

type Message

type Message struct {
	From     peer.ID
	Data     []byte
	Seqno    []byte
	TopicIDs []string

Message is a pubsub message.

type MfsLsEntry added in v0.1.0

type MfsLsEntry struct {
	Name string
	Type uint8
	Size uint64
	Hash string
type ObjectLink struct {
	Name, Hash string
	Size       uint64

type ObjectStats

type ObjectStats struct {
	Hash           string
	BlockSize      int
	CumulativeSize int
	DataSize       int
	LinksSize      int
	NumLinks       int

type PeerInfo

type PeerInfo struct {
	Addrs []string
	ID    string

type PeerStatus added in v0.4.0

type PeerStatus struct {
	ID     string
	Status string

type PeeringLsOutput added in v0.4.0

type PeeringLsOutput struct {
	Peers []PeerInfo

type PeersList

type PeersList struct {
	Peers []string

type PinInfo

type PinInfo struct {
	Type string

type PinStreamInfo added in v0.1.0

type PinStreamInfo struct {
	Cid  string
	Type string

PinStreamInfo is the output type for PinsStream

type PinType added in v0.3.0

type PinType string
const (
	DirectPin    PinType = "direct"
	RecursivePin PinType = "recursive"
	IndirectPin  PinType = "indirect"

type PubSubSubscription

type PubSubSubscription struct {
	// contains filtered or unexported fields

PubSubSubscription allow you to receive pubsub records that where published on the network.

func (*PubSubSubscription) Cancel

func (s *PubSubSubscription) Cancel() error

Cancel cancels the given subscription.

func (*PubSubSubscription) Next

func (s *PubSubSubscription) Next() (*Message, error)

Next waits for the next record and returns that.

type PublishResponse

type PublishResponse struct {
	Name  string `json:"name"`
	Value string `json:"value"`

type Request

type Request struct {
	Ctx     context.Context
	ApiBase string
	Command string
	Args    []string
	Opts    map[string]string
	Body    io.Reader
	Headers map[string]string

func NewRequest

func NewRequest(ctx context.Context, url, command string, args ...string) *Request

func (*Request) Send

func (r *Request) Send(c *http.Client) (*Response, error)

type RequestBuilder

type RequestBuilder struct {
	// contains filtered or unexported fields

RequestBuilder is an IPFS commands request builder.

func (*RequestBuilder) Arguments

func (r *RequestBuilder) Arguments(args ...string) *RequestBuilder

Arguments adds the arguments to the args.

func (*RequestBuilder) Body

func (r *RequestBuilder) Body(body io.Reader) *RequestBuilder

Body sets the request body to the given reader.

func (*RequestBuilder) BodyBytes

func (r *RequestBuilder) BodyBytes(body []byte) *RequestBuilder

BodyBytes sets the request body to the given buffer.

func (*RequestBuilder) BodyString

func (r *RequestBuilder) BodyString(body string) *RequestBuilder

BodyString sets the request body to the given string.

func (*RequestBuilder) Exec

func (r *RequestBuilder) Exec(ctx context.Context, res interface{}) error

Exec sends the request a request and decodes the response.

func (*RequestBuilder) Header

func (r *RequestBuilder) Header(name, value string) *RequestBuilder

Header sets the given header.

func (*RequestBuilder) Option

func (r *RequestBuilder) Option(key string, value interface{}) *RequestBuilder

Option sets the given option.

func (*RequestBuilder) Send

func (r *RequestBuilder) Send(ctx context.Context) (*Response, error)

Send sends the request and return the response.

type Response

type Response struct {
	Output io.ReadCloser
	Error  *Error

func (*Response) Close

func (r *Response) Close() error

func (*Response) Decode

func (r *Response) Decode(dec interface{}) error

type Shell

type Shell struct {
	// contains filtered or unexported fields

func NewLocalShell

func NewLocalShell() *Shell

func NewShell

func NewShell(url string) *Shell

func NewShellWithClient

func NewShellWithClient(url string, client *gohttp.Client) *Shell

func (*Shell) Add

func (s *Shell) Add(r io.Reader, options ...AddOpts) (string, error)

Add adds a file to ipfs pinning it with the given options

func (*Shell) AddDir

func (s *Shell) AddDir(dir string, options ...AddOpts) (string, error)

AddDir adds a directory recursively with all of the files under it

func (s *Shell) AddLink(target string) (string, error)

func (*Shell) AddNoPin

func (s *Shell) AddNoPin(r io.Reader) (string, error)

AddNoPin adds a file to ipfs without pinning it Deprecated: Use Add() with option functions instead

func (*Shell) AddWithOpts

func (s *Shell) AddWithOpts(r io.Reader, pin bool, rawLeaves bool) (string, error)

AddWithOpts adds a file to ipfs with some additional options Deprecated: Use Add() with option functions instead

func (*Shell) BlockGet

func (s *Shell) BlockGet(path string) ([]byte, error)

func (*Shell) BlockPut

func (s *Shell) BlockPut(block []byte, format, mhtype string, mhlen int) (string, error)

func (*Shell) BlockStat

func (s *Shell) BlockStat(path string) (string, int, error)

func (*Shell) BootstrapAdd

func (s *Shell) BootstrapAdd(peers []string) ([]string, error)

func (*Shell) BootstrapAddDefault

func (s *Shell) BootstrapAddDefault() ([]string, error)

func (*Shell) BootstrapRmAll

func (s *Shell) BootstrapRmAll() ([]string, error)

func (*Shell) Cat

func (s *Shell) Cat(path string) (io.ReadCloser, error)

Cat the content at the given path. Callers need to drain and close the returned reader after usage.

func (*Shell) DagGet

func (s *Shell) DagGet(ref string, out interface{}) error

func (*Shell) DagImport added in v0.5.0

func (s *Shell) DagImport(data interface{}, silent, stats bool) (*DagImportOutput, error)

DagImport imports the contents of .car files (with default parameters)

func (*Shell) DagImportWithOpts added in v0.5.0

func (s *Shell) DagImportWithOpts(data interface{}, opts ...options.DagImportOption) (*DagImportOutput, error)

DagImportWithOpts imports the contents of .car files

func (*Shell) DagPut

func (s *Shell) DagPut(data interface{}, inputCodec, storeCodec string) (string, error)

func (*Shell) DagPutWithOpts

func (s *Shell) DagPutWithOpts(data interface{}, opts ...options.DagPutOption) (string, error)

func (*Shell) FileList

func (s *Shell) FileList(path string) (*UnixLsObject, error)

FileList entries at the given path using the UnixFS commands

func (*Shell) FilesChcid added in v0.1.0

func (s *Shell) FilesChcid(ctx context.Context, path string, options ...FilesOpt) error

FilesChcid change the cid version or hash function of the root node of a given path

func (*Shell) FilesCp added in v0.1.0

func (s *Shell) FilesCp(ctx context.Context, src string, dest string, options ...FilesOpt) error

FilesCp copy any IPFS files and directories into MFS (or copy within MFS)

func (*Shell) FilesFlush added in v0.1.0

func (s *Shell) FilesFlush(ctx context.Context, path string) (string, error)

FilesFlush flush a given path's data to disk

func (*Shell) FilesLs added in v0.1.0

func (s *Shell) FilesLs(ctx context.Context, path string, options ...FilesOpt) ([]*MfsLsEntry, error)

FilesLs list directories in the local mutable namespace

func (*Shell) FilesMkdir added in v0.1.0

func (s *Shell) FilesMkdir(ctx context.Context, path string, options ...FilesOpt) error

FilesMkdir make directories

func (*Shell) FilesMv added in v0.1.0

func (s *Shell) FilesMv(ctx context.Context, src string, dest string) error

FilesMv move files

func (*Shell) FilesRead added in v0.1.0

func (s *Shell) FilesRead(ctx context.Context, path string, options ...FilesOpt) (io.ReadCloser, error)

FilesRead read a file in a given MFS

func (*Shell) FilesRm added in v0.1.0

func (s *Shell) FilesRm(ctx context.Context, path string, force bool) error

FilesRm remove a file

func (*Shell) FilesStat added in v0.1.0

func (s *Shell) FilesStat(ctx context.Context, path string, options ...FilesOpt) (*FilesStatObject, error)

FilesStat display file status

func (*Shell) FilesWrite added in v0.1.0

func (s *Shell) FilesWrite(ctx context.Context, path string, data io.Reader, options ...FilesOpt) error

FilesWrite write to a mutable file in a given filesystem

func (*Shell) FindPeer

func (s *Shell) FindPeer(peer string) (*PeerInfo, error)

func (*Shell) Get

func (s *Shell) Get(hash, outdir string) error

func (*Shell) ID

func (s *Shell) ID(peer ...string) (*IdOutput, error)

ID gets information about a given peer. Arguments:

peer: peer.ID of the node to look up. If no peer is specified,

return information about the local peer.

func (*Shell) IsUp

func (s *Shell) IsUp() bool

func (*Shell) KeyGen added in v0.2.0

func (s *Shell) KeyGen(ctx context.Context, name string, options ...KeyOpt) (*Key, error)

KeyGen Create a new keypair

func (*Shell) KeyImport added in v0.4.0

func (s *Shell) KeyImport(ctx context.Context, name string, key io.Reader, options ...KeyImportOpt) error

KeyImport imports key as file.

func (*Shell) KeyList added in v0.2.0

func (s *Shell) KeyList(ctx context.Context) ([]*Key, error)

KeyList List all local keypairs

func (*Shell) KeyRename added in v0.2.0

func (s *Shell) KeyRename(ctx context.Context, old string, new string, force bool) (*KeyRenameObject, error)

KeyRename Rename a keypair

func (*Shell) KeyRm added in v0.2.0

func (s *Shell) KeyRm(ctx context.Context, name string) ([]*Key, error)

KeyRm remove a keypair

func (*Shell) List

func (s *Shell) List(path string) ([]*LsLink, error)

List entries at the given path

func (*Shell) NewObject

func (s *Shell) NewObject(template string) (string, error)

func (*Shell) ObjectGet

func (s *Shell) ObjectGet(path string) (*IpfsObject, error)

func (*Shell) ObjectPut

func (s *Shell) ObjectPut(obj *IpfsObject) (string, error)

func (*Shell) ObjectStat

func (s *Shell) ObjectStat(key string) (*ObjectStats, error)

ObjectStat gets stats for the DAG object named by key. It returns the stats of the requested Object or an error.

func (*Shell) Patch

func (s *Shell) Patch(root, action string, args ...string) (string, error)

func (*Shell) PatchData

func (s *Shell) PatchData(root string, set bool, data interface{}) (string, error)
func (s *Shell) PatchLink(root, path, childhash string, create bool) (string, error)

func (*Shell) Pin

func (s *Shell) Pin(path string) error

Pin the given path

func (*Shell) Pins

func (s *Shell) Pins() (map[string]PinInfo, error)

Pins returns a map of the pin hashes to their info (currently just the pin type, one of DirectPin, RecursivePin, or IndirectPin). A map is returned instead of a slice because it is easier to do existence lookup by map key than unordered array searching. The map is likely to be more useful to a client than a flat list.

func (*Shell) PinsOfType added in v0.3.0

func (s *Shell) PinsOfType(ctx context.Context, pinType PinType) (map[string]PinInfo, error)

Pins returns a map of the pins of specified type (DirectPin, RecursivePin, or IndirectPin)

func (*Shell) PinsStream added in v0.1.0

func (s *Shell) PinsStream(ctx context.Context) (<-chan PinStreamInfo, error)

PinsStream is a streamed version of Pins. It returns a channel of the pins with their type, one of DirectPin, RecursivePin, or IndirectPin.

func (*Shell) PubSubPublish

func (s *Shell) PubSubPublish(topic, data string) (err error)

func (*Shell) PubSubSubscribe

func (s *Shell) PubSubSubscribe(topic string) (*PubSubSubscription, error)

func (*Shell) Publish

func (s *Shell) Publish(node string, value string) error

Publish updates a mutable name to point to a given value

func (*Shell) PublishWithDetails

func (s *Shell) PublishWithDetails(contentHash, key string, lifetime, ttl time.Duration, resolve bool) (*PublishResponse, error)

PublishWithDetails is used for fine grained control over record publishing

func (*Shell) Refs

func (s *Shell) Refs(hash string, recursive bool) (<-chan string, error)

func (*Shell) Request

func (s *Shell) Request(command string, args ...string) *RequestBuilder

func (*Shell) Resolve

func (s *Shell) Resolve(id string) (string, error)

Resolve gets resolves the string provided to an /ipns/[name]. If asked to resolve an empty string, resolve instead resolves the node's own /ipns value.

func (*Shell) ResolvePath

func (s *Shell) ResolvePath(path string) (string, error)

func (*Shell) SetTimeout

func (s *Shell) SetTimeout(d time.Duration)

func (*Shell) StatsBW

func (s *Shell) StatsBW(ctx context.Context) (*p2pmetrics.Stats, error)

ObjectStat gets stats for the DAG object named by key. It returns the stats of the requested Object or an error.

func (*Shell) SwarmConnect

func (s *Shell) SwarmConnect(ctx context.Context, addr ...string) error

SwarmConnect opens a swarm connection to a specific address.

func (*Shell) SwarmPeeringAdd added in v0.4.0

func (s *Shell) SwarmPeeringAdd(ctx context.Context, addr string) (*PeerStatus, error)

SwarmPeeringAdd adds a peer into the peering subsysytem.

func (*Shell) SwarmPeeringLs added in v0.4.0

func (s *Shell) SwarmPeeringLs(ctx context.Context) (*PeeringLsOutput, error)

SwarmPeeringLs lists peers registered in the peering subsystem

func (*Shell) SwarmPeers

func (s *Shell) SwarmPeers(ctx context.Context) (*SwarmConnInfos, error)

SwarmPeers gets all the swarm peers

func (*Shell) Unpin

func (s *Shell) Unpin(path string) error

Unpin the given path

func (*Shell) Version

func (s *Shell) Version() (string, string, error)

returns ipfs version and commit sha

type SwarmConnInfo

type SwarmConnInfo struct {
	Addr    string
	Peer    string
	Latency string
	Muxer   string
	Streams []SwarmStreamInfo

type SwarmConnInfos

type SwarmConnInfos struct {
	Peers []SwarmConnInfo

type SwarmStreamInfo

type SwarmStreamInfo struct {
	Protocol string
type UnixLsLink struct {
	Hash string
	Name string
	Size uint64
	Type string

type UnixLsObject

type UnixLsObject struct {
	Hash  string
	Size  uint64
	Type  string
	Links []*UnixLsLink


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL