docs: document --api flag and api file for remote node access

lidel · lidel · commit d773048c84ec · 2025-12-02T22:15:48.000+01:00
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.
diff --git 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
@@ -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 <rpc-api-addr>` 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/<port> id` in the CLI.
-
-You can use `mkdir -p ~/.ipfs && echo "/ip4/<ip>/tcp/<rpc-port>" > ~/.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
@@ -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/<something>
     ```
 
+    :::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
@@ -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
@@ -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
