From d773048c84ec2dd31e0b6a7a28236ba263e8d339 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 2 Dec 2025 20:20:07 +0100 Subject: [PATCH] docs: document --api flag and api file for remote node access add documentation for connecting to remote IPFS nodes: - --api flag for per-command override - $IPFS_PATH/api file for persistent configuration updated in both CLI reference and quick-start guide with cross-references between them. --- docs/how-to/command-line-quick-start.md | 48 ++++++++++++++++++++++++ docs/install/command-line.md | 33 +++------------- docs/install/run-ipfs-inside-docker.md | 4 ++ docs/reference/kubo/cli.md | 26 +++++++++++-- docs/reference/kubo/generate-cli-docs.sh | 24 +++++++++++- 5 files changed, 102 insertions(+), 33 deletions(-) diff --git a/docs/how-to/command-line-quick-start.md b/docs/how-to/command-line-quick-start.md index 10c4bdfe9..c0faf955c 100644 --- a/docs/how-to/command-line-quick-start.md +++ b/docs/how-to/command-line-quick-start.md @@ -202,6 +202,54 @@ Next, take your node online and interact with the IPFS network: By default, your gateway is not exposed to the world. It only works locally. +## Interact with a remote node + +By default, CLI commands talk to the daemon running on your local machine. If your daemon runs on a different machine or inside a container, there are two ways to connect to it. + +### Using the --api flag + +Use the `--api` flag to specify the remote API address: + +```bash +ipfs --api /ip4/192.168.1.100/tcp/5001 id +``` + +The address uses [multiaddr](../concepts/glossary.md#multiaddr) format. Some common examples: + +- `/ip4/192.168.1.100/tcp/5001` - IPv4 address +- `/ip6/::1/tcp/5001` - IPv6 address +- `/dns/node.example.com/tcp/5001` - DNS name + +### Using the `api` file + +To avoid passing `--api` to every command, create an `api` file in your IPFS repository containing the multiaddr of the remote API: + +```bash +echo "/ip4/192.168.1.100/tcp/5001" > ~/.ipfs/api +``` + +Now all commands will use the remote node: + +```bash +ipfs id +``` + +:::tip +Kubo creates `$IPFS_PATH/api` automatically when `ipfs daemon` starts. You can also create this file manually to connect to: + +- A Kubo node running in Docker or another container +- A remote server running `ipfs daemon` +- An [IPFS Desktop](../install/ipfs-desktop.md) node (the `api` file is created automatically at `~/.ipfs/api`) + +The `--api` flag takes precedence over the `api` file. +::: + +For TLS-secured remote APIs with authentication (`--api-auth`), see [Securing Kubo RPC API](kubo-rpc-tls-auth.md). + +:::tip Read-only access +If you only need to retrieve content without pinning or adding files, consider using the [HTTP Gateway](../reference/http/gateway.md) instead. +::: + ## Interact with the node using the web console You can view the web console for your local node by navigating to `localhost:5001/webui`. diff --git a/docs/install/command-line.md b/docs/install/command-line.md index 52134da7b..6abd9a4f2 100644 --- a/docs/install/command-line.md +++ b/docs/install/command-line.md @@ -319,38 +319,15 @@ For the current instructions on how to manually download, compile and build Kubo ## Determining which node to use with the command line -The command line can detect and use any node that's running, unless it's configured to use an external binary file. Here's which node to use for the local daemon or a remote client: +The CLI automatically connects to a running IPFS daemon by reading the `$IPFS_PATH/api` file (usually `~/.ipfs/api`), which contains the [RPC API](../reference/kubo/rpc.md) address. -### Local daemon - -The local daemon process is automatically started in the CLI with the command `ipfs daemon`. It creates an `$IPFS_PATH/api` file with an [RPC API](../reference/kubo/rpc.md#http-rpc-api-reference) address. - -### Remote client - -You can install the standalone IPFS CLI client independently and use it to talk to an IPFS Desktop (Kubo) node. Use the [RPC API](../reference/kubo/rpc.md#http-rpc-api-reference) to talk to the `ipfs` daemon. - -When an IPFS command executes without parameters, the CLI client checks whether the `$IPFS_PATH/api` file exists and connects to the address listed there. - -- If an `$IPFS_PATH` is in the default location (for example, `~/.ipfs` on Linux), then it works automatically and the IPFS CLI client talks to the locally running `ipfs` daemon without any extra configuration. - -- If an `$IPFS_PATH` isn't in the default location, use the `--api ` command-line argument. Alternatively, you can set the environment variable to `IPFS_PATH`. `IPFS_PATH` will point to a directory with the `$IPFS_PATH/api` file pointing at the Kubo RPC of the existing `ipfs` daemon instance. - -::: tip - -If you plan to expose the RPC API to the public internet with TLS encryption and HTTP authentication, check out the [TLS and HTTP Auth for Kubo with Caddy](../how-to/kubo-rpc-tls-auth.md) guide. - -If you are just interested in retrieval, see implementation-agnostic [HTTP Gateway](../reference/http/gateway.md) instead. +- **Local daemon**: Running `ipfs daemon` creates this file automatically. +- **Remote node**: To connect to a daemon on another machine or in a container, see [Interact with a remote node](../how-to/command-line-quick-start.md#interact-with-a-remote-node). +:::tip +For TLS-secured APIs, see [Secure Kubo RPC with TLS and HTTP Auth](../how-to/kubo-rpc-tls-auth.md). If you are just interested in retrieval, see implementation-agnostic [HTTP Gateway](../reference/http/gateway.md) instead. ::: -#### Most common examples - -If you are an IPFS Desktop user, you can install CLI tools and an `.ipfs/api` file is automatically picked up. - -If you're not running IPFS Desktop, specify a custom port with `ipfs --api /ip4/127.0.0.1/tcp/ id` in the CLI. - -You can use `mkdir -p ~/.ipfs && echo "/ip4//tcp/" > ~/.ipfs/api` to avoid passing `--api` every time. - ## Next steps Now that you've installed IPFS Kubo: diff --git a/docs/install/run-ipfs-inside-docker.md b/docs/install/run-ipfs-inside-docker.md index cdf8eac5c..517d3507d 100644 --- a/docs/install/run-ipfs-inside-docker.md +++ b/docs/install/run-ipfs-inside-docker.md @@ -62,6 +62,10 @@ You can run Kubo IPFS inside Docker to simplify your deployment processes, as we docker exec ipfs_host ipfs add -r /export/ ``` + :::tip Using your local ipfs CLI + If you have `ipfs` installed on the host and the RPC API port is exposed, you can run commands without `docker exec`. See [Interact with a remote node](../how-to/command-line-quick-start.md#interact-with-a-remote-node) for details. + ::: + 1. Stop the running container: ```shell diff --git a/docs/reference/kubo/cli.md b/docs/reference/kubo/cli.md index ac8d01ab9..9826697ec 100644 --- a/docs/reference/kubo/cli.md +++ b/docs/reference/kubo/cli.md @@ -5,7 +5,7 @@ description: API documentation for the Kubo command-line executable. # Kubo command-line -::: tip Generated on 2025-11-27 03:54:28, from kubo 0.39.0 +::: tip Generated on 2025-12-02 22:04:13, from kubo 0.39.0 This document was autogenerated from CLI help text in [kubo 0.39.0](https://github.com/ipfs/kubo/releases/tag/v0.39.0) For issues and support, check out the [generate-cli-docs.sh](https://github.com/ipfs/ipfs-docs/blob/main/docs/reference/kubo/generate-cli-docs.sh) script on GitHub. ::: @@ -14,13 +14,13 @@ For issues and support, check out the [generate-cli-docs.sh](https://github.com/ IPFS can run in either _online_ or _offline_ mode. Online mode is when you have IPFS running separately as a daemon process. If you do not have an IPFS daemon running, you are in offline mode. Some commands, like `ipfs swarm peers`, are only supported when online. -The [command-line quickstart guide](/how-to/command-line-quick-start/#take-your-node-online) explains how to start the IPFS daemon and take your node online. +The [command-line quickstart guide](../../how-to/command-line-quick-start.md#take-your-node-online) explains how to start the IPFS daemon and take your node online. ### Alignment with Kubo RPC API -Every command usable from the CLI is also available through the [RPC API v0](/reference/kubo/rpc). For example: +Every command usable from the CLI is also available through the [RPC API v0](rpc.md). For example: ```sh > ipfs swarm peers @@ -38,6 +38,26 @@ Every command usable from the CLI is also available through the [RPC API v0](/re } ``` +### Connecting to a Remote API + +By default, CLI commands connect to the local daemon at `/ip4/127.0.0.1/tcp/5001`. There are two ways to connect to a different instance: + +1. Use the `--api` flag: + + ```sh + ipfs --api /ip4/192.168.1.100/tcp/5001 id + ``` + +2. Create an `api` file in your IPFS repository (`$IPFS_PATH/api`, usually `~/.ipfs/api`) containing the [multiaddr](../../concepts/glossary.md#multiaddr) of the API endpoint: + + ```sh + echo /ip4/192.168.1.100/tcp/5001 > ~/.ipfs/api + ipfs id + ``` + + Kubo creates this file automatically when `ipfs daemon` starts. Creating it manually lets you use a remote node without passing `--api` to every command. + +For a step-by-step guide, see [Interact with a remote node](../../how-to/command-line-quick-start.md#interact-with-a-remote-node). For TLS-secured APIs with authentication (`--api-auth`), see [Securing Kubo RPC API](../../how-to/kubo-rpc-tls-auth.md). ## ipfs diff --git a/docs/reference/kubo/generate-cli-docs.sh b/docs/reference/kubo/generate-cli-docs.sh index 8cbdc7fad..a4e7ae8e9 100755 --- a/docs/reference/kubo/generate-cli-docs.sh +++ b/docs/reference/kubo/generate-cli-docs.sh @@ -21,14 +21,14 @@ For issues and support, check out the [generate-cli-docs.sh](https://github.com/ IPFS can run in either _online_ or _offline_ mode. Online mode is when you have IPFS running separately as a daemon process. If you do not have an IPFS daemon running, you are in offline mode. Some commands, like \`ipfs swarm peers\`, are only supported when online. -The [command-line quickstart guide](/how-to/command-line-quick-start/#take-your-node-online) explains how to start the IPFS daemon and take your node online. +The [command-line quickstart guide](../../how-to/command-line-quick-start.md#take-your-node-online) explains how to start the IPFS daemon and take your node online. " echo " ### Alignment with Kubo RPC API -Every command usable from the CLI is also available through the [RPC API v0](/reference/kubo/rpc). For example: +Every command usable from the CLI is also available through the [RPC API v0](rpc.md). For example: \`\`\`sh > ipfs swarm peers @@ -46,6 +46,26 @@ Every command usable from the CLI is also available through the [RPC API v0](/re } \`\`\` +### Connecting to a Remote API + +By default, CLI commands connect to the local daemon at \`/ip4/127.0.0.1/tcp/5001\`. There are two ways to connect to a different instance: + +1. Use the \`--api\` flag: + + \`\`\`sh + ipfs --api /ip4/192.168.1.100/tcp/5001 id + \`\`\` + +2. Create an \`api\` file in your IPFS repository (\`\$IPFS_PATH/api\`, usually \`~/.ipfs/api\`) containing the [multiaddr](../../concepts/glossary.md#multiaddr) of the API endpoint: + + \`\`\`sh + echo "/ip4/192.168.1.100/tcp/5001" > ~/.ipfs/api + ipfs id + \`\`\` + + Kubo creates this file automatically when \`ipfs daemon\` starts. Creating it manually lets you use a remote node without passing \`--api\` to every command. + +For a step-by-step guide, see [Interact with a remote node](../../how-to/command-line-quick-start.md#interact-with-a-remote-node). For TLS-secured APIs with authentication (\`--api-auth\`), see [Securing Kubo RPC API](../../how-to/kubo-rpc-tls-auth.md). " printf "\n" ipfs commands | while read line ; do